Merge pull request #295 from flashcatcloud/docs/platform-safari-field-descriptions

docs(api): document platform and safari schema fields

Author: ysyneu

api-reference/openapi.en.json

@@ -31179,7 +31179,8 @@
         "properties": {
           "request_id": {
             "type": "string",
-            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4"
+            "example": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
+            "description": "Unique trace ID of this request; include it when reporting issues so logs can be located."
           },
           "error": {
             "$ref": "#/components/schemas/DutyError"
@@ -45977,7 +45978,7 @@
               "zh-CN",
               "en-US"
             ],
-            "description": "Locale"
+            "description": "Locale. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400."
           },
           "time_zone": {
             "type": "string",
@@ -46212,7 +46213,7 @@
               "zh-CN",
               "en-US"
             ],
-            "description": "New locale preference."
+            "description": "New locale preference. One of: `zh-CN` (Simplified Chinese), `en-US` (English); other values are rejected with a 400."
           },
           "time_zone": {
             "type": "string",
@@ -46454,17 +46455,20 @@
         "properties": {
           "team_id": {
             "type": "integer",
-            "format": "uint64"
+            "format": "uint64",
+            "description": "Team ID."
           },
           "team_name": {
-            "type": "string"
+            "type": "string",
+            "description": "Team name."
           },
           "person_ids": {
             "type": "array",
             "items": {
               "type": "integer",
               "format": "uint64"
-            }
+            },
+            "description": "Array of person IDs belonging to the team; empty array (never null) when the team has no members."
           }
         }
       },
@@ -46479,7 +46483,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/TeamBriefItem"
-            }
+            },
+            "description": "Array of brief team info for the matched `team_ids`; may be null when no ID matches."
           }
         }
       },
@@ -46550,7 +46555,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/TeamItem"
-            }
+            },
+            "description": "Array of teams for the current page, used with `p`, `limit` and `total` for pagination; empty array on an empty page."
           }
         }
       },
@@ -46776,7 +46782,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/RoleItem"
-            }
+            },
+            "description": "Array of roles; includes account roles plus built-in global roles unless `no_global=true`; empty array when no results."
           }
         }
       },
@@ -46878,7 +46885,7 @@
               "read",
               "manage"
             ],
-            "description": "Whether this is a read or manage permission."
+            "description": "Whether this is a read or manage permission. `read`: view-only permission (read/list/query); `manage`: administrative permission covering mutations (create, update, delete, configure)."
           },
           "description": {
             "type": "string",
@@ -46917,7 +46924,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/PermissionItem"
-            }
+            },
+            "description": "Array of permission items: system-level permissions plus the caller's account-scoped custom-menu permissions (never other tenants' rows)."
           }
         }
       },
@@ -46962,7 +46970,7 @@
               "menu",
               "url"
             ],
-            "description": "Factor type."
+            "description": "Factor type. `api`: backend API factor — `factor_name` is the API name (e.g. `skill:write:upload`), enforced at the gateway; `button`: UI action factor, used by the role-config page to render action toggles; `visit`: page-visit factor (custom menu pages use this type); `menu`: menu-visibility factor (legacy, no current seed data); `url`: page route-path factor (legacy, no current seed data)."
           }
         }
       },
@@ -47122,10 +47130,12 @@
               "type": "object",
               "properties": {
                 "Key": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "Name of a URL path parameter (the `:xxx` placeholder in the route)."
                 },
                 "Value": {
-                  "type": "string"
+                  "type": "string",
+                  "description": "The actual value of that path parameter in this request."
                 }
               }
             },
@@ -47204,7 +47214,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/AuditOperationTypeItem"
-            }
+            },
+            "description": "Array of all auditable operation types (only APIs flagged for audit); always an array, possibly empty."
           }
         }
       },
@@ -50889,7 +50900,7 @@
           },
           "auth_mode": {
             "type": "string",
-            "description": "Authentication mode.",
+            "description": "Authentication mode. One of: `shared` (a single static credential saved on the resource and shared by all callers in the account; the default — an empty value behaves the same), `per_user_secret` (each user stores their own secret per `secret_schema`, injected per user at runtime), `per_user_oauth` (each user completes their own OAuth grant; discovery and registration run lazily on first use).",
             "enum": [
               "shared",
               "per_user_secret",
@@ -51173,7 +51184,7 @@
           },
           "environment_kind": {
             "type": "string",
-            "description": "Runtime environment kind. Omit or send an empty value for automatic selection.",
+            "description": "Runtime environment kind. Omit or send an empty value for automatic selection. One of: `cloud` (platform-hosted cloud sandbox), `byoc` (a self-hosted BYOC runner in the account, used with `environment_id`); automatic selection prefers an online BYOC runner and falls back to the cloud sandbox.",
             "enum": [
               "",
               "cloud",
@@ -51269,7 +51280,7 @@
               "person",
               "team"
             ],
-            "description": "Hidden session run scope."
+            "description": "Hidden session run scope. One of: `person` (personal rule, team_id=0, runs as the creator; disabled when the creator leaves the account), `team` (team rule, team_id>0, owned by the team and shared with its members; survives the creator leaving). Derived from the rule's team_id."
           },
           "cron_expr": {
             "type": "string",
@@ -51285,7 +51296,7 @@
           },
           "environment_kind": {
             "type": "string",
-            "description": "Runtime environment kind. Omit or send an empty value for automatic selection.",
+            "description": "Runtime environment kind. Omit or send an empty value for automatic selection. One of: `cloud` (platform-hosted cloud sandbox), `byoc` (self-hosted BYOC runner in the account); an empty value means automatic selection (prefers an online BYOC runner, falls back to the cloud sandbox).",
             "enum": [
               "",
               "cloud",
@@ -51456,7 +51467,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationRuleItem"
-            }
+            },
+            "description": "Array of automation rules for the current page, used with `total` for pagination."
           }
         },
         "required": [
@@ -51617,7 +51629,7 @@
               "http_post",
               "oncall_incident"
             ],
-            "description": "Trigger kind."
+            "description": "Trigger kind. One of:\n| Value | Meaning |\n| --- | --- |\n| `schedule` | Fired by the rule's schedule trigger |\n| `debug` | Debug run (reserved; current rule runs never carry this kind) |\n| `manual` | Triggered manually by a user |\n| `http_post` | Fired via the rule's HTTP POST webhook |\n| `oncall_incident` | Fired by an on-call incident event |"
           },
           "occurrence_key": {
             "type": "string",
@@ -51635,7 +51647,7 @@
               "skipped",
               "abandoned"
             ],
-            "description": "Run status."
+            "description": "Run status. One of (the first three are in-flight, the rest terminal):\n| Value | Meaning |\n| --- | --- |\n| `queued` | Enqueued, waiting for a worker |\n| `running` | Executing |\n| `retrying` | An attempt failed and a retry is scheduled |\n| `succeeded` | Completed successfully |\n| `partial` | Partially succeeded (currently only produced by memory-consolidation runs; rule runs never reach it) |\n| `failed` | Terminal failure, no further retries |\n| `skipped` | Not executed (e.g. grace period expired, trigger or rule invalid); the reason is kept on the run record |\n| `abandoned` | Still in-flight past the stale threshold and swept as never-completed (e.g. worker died) |"
           },
           "attempts": {
             "type": "integer",
@@ -51767,7 +51779,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationRunItem"
-            }
+            },
+            "description": "Array of run records for the given `rule_id`, filtered by the request's status/trigger-kind/time-range and paginated."
           }
         },
         "required": [
@@ -51841,7 +51854,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/AutomationTemplateItem"
-            }
+            },
+            "description": "Array of built-in automation templates, with display text localized by the request `locale` (falling back to request headers)."
           }
         },
         "required": [
@@ -51977,7 +51991,7 @@
           },
           "status": {
             "type": "string",
-            "description": "Event status.",
+            "description": "Event status. One of: `normal` (a live event included in the context fed to the model), `compressed` (folded into a compaction summary boundary event; no longer loaded for the model, kept as history only).",
             "enum": [
               "normal",
               "compressed"
@@ -52087,7 +52101,7 @@
           },
           "environment_kind": {
             "type": "string",
-            "description": "Pin the server to a specific BYOC runner (`environment_id` required). Omit or send empty for automatic selection; `cloud` is not supported for MCP servers.",
+            "description": "Pin the server to a specific BYOC runner (`environment_id` required). Omit or send empty for automatic selection; `cloud` is not supported for MCP servers. The only accepted value: `byoc` (a self-hosted BYOC runner in the account; the MCP server process runs on the customer's own infrastructure).",
             "enum": [
               "byoc"
             ]
@@ -52189,7 +52203,7 @@
           },
           "transport": {
             "type": "string",
-            "description": "Transport protocol.",
+            "description": "Transport protocol. One of: `stdio` (standard I/O to a local subprocess), `sse` (standalone SSE, the legacy MCP transport), `streamable-http` (the newer HTTP streaming transport).",
             "enum": [
               "stdio",
               "sse",
@@ -52270,7 +52284,7 @@
           },
           "auth_mode": {
             "type": "string",
-            "description": "Authentication mode.",
+            "description": "Authentication mode. One of: `shared` (a single static credential saved on the resource and shared by all callers in the account; the default — an empty value behaves the same), `per_user_secret` (each user stores their own secret per `secret_schema`, injected per user at runtime), `per_user_oauth` (each user completes their own OAuth grant; discovery and registration run lazily on first use).",
             "enum": [
               "shared",
               "per_user_secret",
@@ -52594,7 +52608,7 @@
               "person",
               "team"
             ],
-            "description": "Resolved run scope for this run; mirrors the rule's run_scope."
+            "description": "Resolved run scope for this run; mirrors the rule's run_scope. One of: `person` (personal rule, runs as its creator), `team` (team rule, runs under the owning team)."
           },
           "owner_id": {
             "type": "integer",
@@ -52750,7 +52764,7 @@
           },
           "entry_kind": {
             "type": "string",
-            "description": "Surface that created the session.",
+            "description": "Surface that created the session. One of:\n| Value | Meaning |\n| --- | --- |\n| `web` | Created from the web console |\n| `im` | Created from an IM client (IM bot / IM H5) |\n| `api` | Created via the public API |\n| `automation` | Created by an automation rule (unattended run) |\n| `subagent` | Child session spawned by a parent's agent_dispatch (audit label; at runtime it executes on the web tool surface) |",
             "enum": [
               "web",
               "im",
@@ -52794,12 +52808,13 @@
           },
           "access_source": {
             "type": "string",
-            "description": "How the caller received access to this session. Omitted when no access source is resolved.",
+            "description": "How the caller received access to this session. Omitted when no access source is resolved. One of:\n| Value | Meaning |\n| --- | --- |\n| `owner` | Caller is the session creator (full access) |\n| `team_member` | Caller belongs to the session's bound team (full access) |\n| `manager` | Manager grant (reserved; never produced by the current version) |\n| `share_link` | Granted via a valid share link (view/fork only; cannot continue or manage) |\n| `participant` | Same-account non-member granted via a participable team session (view/continue/fork only) |",
             "enum": [
               "owner",
               "team_member",
               "manager",
-              "share_link"
+              "share_link",
+              "participant"
             ]
           },
           "share_enabled": {
@@ -52823,7 +52838,7 @@
           },
           "status": {
             "type": "string",
-            "description": "Lifecycle status.",
+            "description": "Lifecycle status. One of: `enabled` (active), `deleted` (soft-deleted, no longer accessible).",
             "enum": [
               "enabled",
               "deleted"
@@ -52952,7 +52967,7 @@
         "properties": {
           "app_name": {
             "type": "string",
-            "description": "Agent app whose sessions to list.",
+            "description": "Agent app whose sessions to list. One of:\n| Value | Meaning |\n| --- | --- |\n| `ask-ai` | Ask AI assistant |\n| `support` | Customer-support agent |\n| `support-website` | Website support agent (exposed over A2A, not built into the console) |\n| `support-flashcat` | Flashcat-site support agent (exposed over A2A) |\n| `ai-sre` | The AI SRE main app |\n| `template-assistant` | Notification-template assistant (template editing/validation) |\n| `swe` | Internal benchmarking app (not customer-facing) |",
             "enum": [
               "ask-ai",
               "support",
@@ -58423,7 +58438,7 @@
         "properties": {
           "code": {
             "type": "string",
-            "description": "Warning code.",
+            "description": "Warning code. One of: `unresolved_reference` (an @ref in the written file's content points to a file that does not exist in the pack; `ref` carries it), `still_referenced_by` (the deleted file is still @ref-referenced by other files in the pack; `refs` lists the referrers).",
             "enum": [
               "unresolved_reference",
               "still_referenced_by"
@@ -58464,7 +58479,7 @@
           },
           "scope": {
             "type": "string",
-            "description": "Restrict to one scope; `all` (default) overrides `include_account`.",
+            "description": "Restrict to one scope; `all` (default) overrides `include_account`. One of: `all` (account scope plus visible team scopes), `account` (account-level packs only), `team` (team-level packs only, can be combined with `team_ids`).",
             "enum": [
               "all",
               "account",
@@ -58499,7 +58514,7 @@
         "properties": {
           "scope": {
             "type": "string",
-            "description": "Scope of the pack to ensure.",
+            "description": "Scope of the pack to ensure. One of: `account` (account-level pack; scope_id is forced to the caller's account ID and only account admins may create it; first creation seeds a default DUTY.md), `team` (team-level pack; the `scope_id` team ID is required and the caller must belong to that team).",
             "enum": [
               "account",
               "team"
@@ -58645,7 +58660,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeFileItem"
-            }
+            },
+            "description": "Array of files in this knowledge pack; empty array when the pack has no files."
           }
         },
         "required": [
@@ -58661,7 +58677,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgePackItem"
-            }
+            },
+            "description": "Array of visible knowledge packs after filtering (current page), used with `total` for pagination."
           },
           "total": {
             "type": "integer",
@@ -58682,7 +58699,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeFileItem"
-            }
+            },
+            "description": "Array of files in the specified knowledge pack; empty array when the pack has no files."
           },
           "total": {
             "type": "integer",
@@ -58723,7 +58741,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
-            }
+            },
+            "description": "Non-blocking warnings after a successful write; `code=unresolved_reference` means an @ref in the file content points to a file that does not exist in the pack. Absent when there are no warnings (omitempty)."
           }
         },
         "required": [
@@ -58759,7 +58778,8 @@
             "type": "array",
             "items": {
               "$ref": "#/components/schemas/KnowledgeWarning"
-            }
+            },
+            "description": "Non-blocking warnings after deletion; `code=still_referenced_by` means the (force-)deleted file is still @ref-referenced by other files in the pack (`refs` lists the referrers). Absent when there are no warnings (omitempty)."
           }
         }
       }