diff --git a/a2a_agents.go b/a2a_agents.go index e389e57..8d69067 100644 --- a/a2a_agents.go +++ b/a2a_agents.go @@ -9,7 +9,7 @@ type A2aAgentsService service // Get A2A agent detail. // -// Return the full configuration of a single A2A agent by ID. +// Get one A2A agent by ID. // // API: POST /safari/a2a-agent/get (remote-agent-read-get). func (s *A2aAgentsService) ReadGet(ctx context.Context, req *A2aAgentIDRequest) (*A2aAgentItem, *Response, error) { @@ -23,7 +23,7 @@ func (s *A2aAgentsService) ReadGet(ctx context.Context, req *A2aAgentIDRequest) // List A2A agents. // -// List registered A2A agents visible to the caller across account and team scopes, with pagination. +// List A2A agents visible to the caller across account and team scopes, with pagination. // // API: POST /safari/a2a-agent/list (remote-agent-read-list). func (s *A2aAgentsService) ReadList(ctx context.Context, req *A2aAgentListRequest) (*A2aAgentListResponse, *Response, error) { @@ -37,7 +37,7 @@ func (s *A2aAgentsService) ReadList(ctx context.Context, req *A2aAgentListReques // Create A2A agent. // -// Register a new A2A remote agent the SRE agent can delegate tasks to. +// Register a new A2A remote agent from its agent-card URL. // // API: POST /safari/a2a-agent/create (remote-agent-write-create). func (s *A2aAgentsService) WriteCreate(ctx context.Context, req *A2aAgentCreateRequest) (*A2aAgentCreateResponse, *Response, error) { @@ -51,7 +51,7 @@ func (s *A2aAgentsService) WriteCreate(ctx context.Context, req *A2aAgentCreateR // Delete A2A agent. // -// Soft-delete an A2A agent registration so it can no longer be used. +// Soft-delete an A2A agent by ID. // // API: POST /safari/a2a-agent/delete (remote-agent-write-delete). func (s *A2aAgentsService) WriteDelete(ctx context.Context, req *A2aAgentIDRequest) (*any, *Response, error) { @@ -65,7 +65,7 @@ func (s *A2aAgentsService) WriteDelete(ctx context.Context, req *A2aAgentIDReque // Disable A2A agent. // -// Deactivate an A2A agent so the SRE agent stops delegating to it. +// Disable an enabled A2A agent. // // API: POST /safari/a2a-agent/disable (remote-agent-write-disable). func (s *A2aAgentsService) WriteDisable(ctx context.Context, req *A2aAgentIDRequest) (*any, *Response, error) { @@ -79,7 +79,7 @@ func (s *A2aAgentsService) WriteDisable(ctx context.Context, req *A2aAgentIDRequ // Enable A2A agent. // -// Activate a disabled A2A agent so the SRE agent can delegate to it. +// Enable a disabled A2A agent. // // API: POST /safari/a2a-agent/enable (remote-agent-write-enable). func (s *A2aAgentsService) WriteEnable(ctx context.Context, req *A2aAgentIDRequest) (*any, *Response, error) { @@ -93,7 +93,7 @@ func (s *A2aAgentsService) WriteEnable(ctx context.Context, req *A2aAgentIDReque // Update A2A agent. // -// Edit an A2A agent's card URL, auth, streaming flag, or owning team. +// Apply a partial update to an A2A agent. Omit a field to leave it unchanged. // // API: POST /safari/a2a-agent/update (remote-agent-write-update). func (s *A2aAgentsService) WriteUpdate(ctx context.Context, req *A2aAgentUpdateRequest) (*any, *Response, error) { diff --git a/mcp_servers.go b/mcp_servers.go index 4578a01..7c9d7a2 100644 --- a/mcp_servers.go +++ b/mcp_servers.go @@ -9,7 +9,7 @@ type McpServersService service // Get MCP server detail. // -// Return the full configuration of a single MCP server, with a live tool catalogue. +// Get one MCP server and run a live probe of its tool list. // // API: POST /safari/mcp/server/get (mcp-read-server-get). func (s *McpServersService) ReadServerGet(ctx context.Context, req *McpServerGetRequest) (*McpServerItem, *Response, error) { @@ -23,7 +23,7 @@ func (s *McpServersService) ReadServerGet(ctx context.Context, req *McpServerGet // List MCP servers. // -// List configured MCP servers visible to the caller across account and team scopes, with pagination. +// List MCP servers visible to the caller across account and team scopes, with pagination. // // API: POST /safari/mcp/server/list (mcp-read-server-list). func (s *McpServersService) ReadServerList(ctx context.Context, req *McpServerListRequest) (*McpServerListResponse, *Response, error) { @@ -37,7 +37,7 @@ func (s *McpServersService) ReadServerList(ctx context.Context, req *McpServerLi // Create MCP server. // -// Register a new MCP server the agent can call tools through. +// Register a new MCP server (connector) on the account. // // API: POST /safari/mcp/server/create (mcp-write-server-create). func (s *McpServersService) WriteServerCreate(ctx context.Context, req *McpServerCreateRequest) (*McpServerItem, *Response, error) { @@ -51,7 +51,7 @@ func (s *McpServersService) WriteServerCreate(ctx context.Context, req *McpServe // Delete MCP server. // -// Permanently remove an MCP server so agents can no longer use its tools. +// Delete an MCP server by ID. // // API: POST /safari/mcp/server/delete (mcp-write-server-delete). func (s *McpServersService) WriteServerDelete(ctx context.Context, req *McpServerDeleteRequest) (*any, *Response, error) { @@ -65,7 +65,7 @@ func (s *McpServersService) WriteServerDelete(ctx context.Context, req *McpServe // Disable MCP server. // -// Deactivate an MCP server so agents stop calling its tools. +// Disable an enabled MCP server. // // API: POST /safari/mcp/server/disable (mcp-write-server-disable). func (s *McpServersService) WriteServerDisable(ctx context.Context, req *McpServerStatusRequest) (*any, *Response, error) { @@ -79,7 +79,7 @@ func (s *McpServersService) WriteServerDisable(ctx context.Context, req *McpServ // Enable MCP server. // -// Activate a disabled MCP server so agents can call its tools. +// Enable a disabled MCP server. // // API: POST /safari/mcp/server/enable (mcp-write-server-enable). func (s *McpServersService) WriteServerEnable(ctx context.Context, req *McpServerStatusRequest) (*any, *Response, error) { @@ -93,7 +93,7 @@ func (s *McpServersService) WriteServerEnable(ctx context.Context, req *McpServe // Update MCP server. // -// Edit an MCP server's connection settings or reassign its owning team. +// Update an MCP server's configuration. Omit a field to leave it unchanged. // // API: POST /safari/mcp/server/update (mcp-write-server-update). func (s *McpServersService) WriteServerUpdate(ctx context.Context, req *McpServerUpdateRequest) (*McpServerItem, *Response, error) { diff --git a/models_gen.go b/models_gen.go index 1ec6a88..85ba36e 100644 --- a/models_gen.go +++ b/models_gen.go @@ -25,7 +25,7 @@ func (e CSVFileResponse) String() string { return string(e) } // DataSourceListResponse is a list response payload. type DataSourceListResponse []DataSourceItem -// ErrorCode 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. +// ErrorCode Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational. type ErrorCode string const ( @@ -178,130 +178,130 @@ type ChannelsChannelEscalateWebhookRobotListResponse struct { // A2aAgentCreateRequest is generated from the Flashduty OpenAPI schema. type A2aAgentCreateRequest struct { - // Display name of the agent. + // Agent display name. AgentName string `json:"agent_name,omitempty" toon:"agent_name,omitempty"` - // Authentication parameters keyed by name. + // Authentication config key-values. AuthConfig map[string]string `json:"auth_config,omitempty" toon:"auth_config,omitempty"` - // Credential model; defaults to shared. + // Authentication mode: shared (default), per_user_secret, or per_user_oauth. AuthMode string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` - // Authentication scheme used when calling the agent. + // Authentication type for the remote agent. AuthType string `json:"auth_type,omitempty" toon:"auth_type,omitempty"` - // URL of the agent's published A2A agent card. + // URL of the remote agent card. CardURL string `json:"card_url,omitempty" toon:"card_url,omitempty"` - // What this agent does and when to delegate to it. + // Agent description. Description string `json:"description,omitempty" toon:"description,omitempty"` - // OAuth metadata JSON; reserved for OAuth-based auth. + // JSON OAuth metadata; reserved for per_user_oauth. OauthMetadata string `json:"oauth_metadata,omitempty" toon:"oauth_metadata,omitempty"` - // JSON schema of the per-user secret; required when auth_mode is per_user_secret. + // JSON secret schema; required when auth_mode=per_user_secret. SecretSchema string `json:"secret_schema,omitempty" toon:"secret_schema,omitempty"` - // Whether the agent supports streaming responses. + // Whether the remote agent supports streaming. Streaming bool `json:"streaming,omitempty" toon:"streaming,omitempty"` - // Owning team for the new agent; 0 for account scope. + // Team scope: 0 = account-wide; >0 = team. TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } // A2aAgentCreateResponse is generated from the Flashduty OpenAPI schema. type A2aAgentCreateResponse struct { - // Identifier of the created agent. + // ID of the newly created agent. AgentID string `json:"agent_id" toon:"agent_id"` } // A2aAgentIDRequest is generated from the Flashduty OpenAPI schema. type A2aAgentIDRequest struct { - // Identifier of the target agent. + // Target agent ID. AgentID string `json:"agent_id,omitempty" toon:"agent_id,omitempty"` } // A2aAgentItem is generated from the Flashduty OpenAPI schema. type A2aAgentItem struct { - // Owning account. + // Owning account ID. AccountID int64 `json:"account_id" toon:"account_id"` - // Name resolved from the fetched agent card. + // Agent name resolved from the remote card. AgentCardName string `json:"agent_card_name" toon:"agent_card_name"` - // Skills advertised on the fetched agent card. + // Skills advertised by the remote card. AgentCardSkills []string `json:"agent_card_skills" toon:"agent_card_skills"` - // Unique identifier of the A2A agent. + // Unique A2A agent ID (prefix `a2a_`). AgentID string `json:"agent_id" toon:"agent_id"` - // Display name of the agent. + // Agent display name. AgentName string `json:"agent_name" toon:"agent_name"` - // Authentication parameters keyed by name. + // Authentication config; secret values are masked. AuthConfig map[string]string `json:"auth_config" toon:"auth_config"` - // Credential model: shared, per_user_secret, or per_user_oauth. + // Authentication mode. AuthMode string `json:"auth_mode" toon:"auth_mode"` - // Authentication scheme used when calling the agent. + // Authentication type for reaching the remote agent. AuthType string `json:"auth_type" toon:"auth_type"` - // Whether the calling member may edit or delete this resource. + // Whether the caller may edit this agent. CanEdit bool `json:"can_edit" toon:"can_edit"` - // Timeout for fetching the agent card, in seconds. + // Card-resolution timeout in seconds. CardResolveTimeout int64 `json:"card_resolve_timeout" toon:"card_resolve_timeout"` - // URL of the agent's published A2A agent card. + // URL of the remote agent card. CardURL string `json:"card_url" toon:"card_url"` - // Creation time as a Unix timestamp in seconds. - CreatedAt Timestamp `json:"created_at" toon:"created_at"` - // Member who created this resource. + // Creation time. Unix timestamp in milliseconds. + CreatedAt TimestampMilli `json:"created_at" toon:"created_at"` + // Member ID that created the agent. CreatedBy int64 `json:"created_by" toon:"created_by"` - // What this agent does and when to delegate to it. + // Agent description. Description string `json:"description" toon:"description"` - // OAuth metadata JSON. + // JSON-encoded OAuth metadata (per_user_oauth mode). OauthMetadata string `json:"oauth_metadata" toon:"oauth_metadata"` - // JSON schema of the per-user secret. + // JSON-encoded secret schema (per_user_secret mode). SecretSchema string `json:"secret_schema" toon:"secret_schema"` - // Whether the agent is active and reachable. + // Agent status. Status string `json:"status" toon:"status"` - // Whether the agent supports streaming responses. + // Whether the remote agent supports streaming responses. Streaming bool `json:"streaming" toon:"streaming"` - // Timeout for a single delegated task, in seconds. + // Single-task execution timeout in seconds. TaskTimeout int64 `json:"task_timeout" toon:"task_timeout"` - // Owning team; 0 means account scope. + // Team scope: 0 = account-wide; >0 = the owning team. TeamID int64 `json:"team_id" toon:"team_id"` - // Last-update time as a Unix timestamp in seconds. - UpdatedAt Timestamp `json:"updated_at" toon:"updated_at"` + // Last update time. Unix timestamp in milliseconds. + UpdatedAt TimestampMilli `json:"updated_at" toon:"updated_at"` } // A2aAgentListRequest is generated from the Flashduty OpenAPI schema. type A2aAgentListRequest struct { - // Include account-scoped rows alongside team-scoped ones; defaults to true. - IncludeAccount bool `json:"include_account,omitempty" toon:"include_account,omitempty"` - // Maximum number of rows to return; defaults to 20. + // Include account-scoped (team_id=0) rows. Defaults to true. + IncludeAccount *bool `json:"include_account,omitempty" toon:"include_account,omitempty"` + // Page size. Limit int64 `json:"limit,omitempty" toon:"limit,omitempty"` - // Number of rows to skip for pagination. + // Row offset for pagination. Offset int64 `json:"offset,omitempty" toon:"offset,omitempty"` - // Restrict results to resources owned by these teams; intersected with the caller's visible set. + // Filter to these team IDs; empty = the caller's visible set. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } // A2aAgentListResponse is generated from the Flashduty OpenAPI schema. type A2aAgentListResponse struct { - // A2A agents on the current page. + // A2A agents on this page. Items []A2aAgentItem `json:"items" toon:"items"` - // Total number of agents matching the filters. + // Total number of matching agents. Total int64 `json:"total" toon:"total"` } // A2aAgentUpdateRequest is generated from the Flashduty OpenAPI schema. type A2aAgentUpdateRequest struct { - // Identifier of the agent to update. + // Target agent ID. AgentID string `json:"agent_id,omitempty" toon:"agent_id,omitempty"` - // New display name. - AgentName string `json:"agent_name,omitempty" toon:"agent_name,omitempty"` - // New authentication parameters. + // New display name. Omit to leave unchanged. + AgentName *string `json:"agent_name,omitempty" toon:"agent_name,omitempty"` + // Replace the auth config. Omit to leave unchanged. AuthConfig map[string]string `json:"auth_config,omitempty" toon:"auth_config,omitempty"` - // New credential model. - AuthMode string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` - // New authentication scheme. - AuthType string `json:"auth_type,omitempty" toon:"auth_type,omitempty"` - // New agent card URL. - CardURL string `json:"card_url,omitempty" toon:"card_url,omitempty"` - // New description. - Description string `json:"description,omitempty" toon:"description,omitempty"` - // New OAuth metadata JSON. - OauthMetadata string `json:"oauth_metadata,omitempty" toon:"oauth_metadata,omitempty"` - // New per-user secret JSON schema. - SecretSchema string `json:"secret_schema,omitempty" toon:"secret_schema,omitempty"` - // Toggle streaming-response support. - Streaming bool `json:"streaming,omitempty" toon:"streaming,omitempty"` - // Reassign the agent to this team; omit to leave unchanged, 0 for account scope. - TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` + // New auth mode: shared, per_user_secret, or per_user_oauth. + AuthMode *string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` + // New auth type. Omit to leave unchanged. + AuthType *string `json:"auth_type,omitempty" toon:"auth_type,omitempty"` + // New card URL. Omit to leave unchanged. + CardURL *string `json:"card_url,omitempty" toon:"card_url,omitempty"` + // New description. Omit to leave unchanged. + Description *string `json:"description,omitempty" toon:"description,omitempty"` + // New JSON OAuth metadata. + OauthMetadata *string `json:"oauth_metadata,omitempty" toon:"oauth_metadata,omitempty"` + // New JSON secret schema. + SecretSchema *string `json:"secret_schema,omitempty" toon:"secret_schema,omitempty"` + // Toggle streaming support. Omit to leave unchanged. + Streaming *bool `json:"streaming,omitempty" toon:"streaming,omitempty"` + // Reassign team scope. Omit to leave unchanged. + TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } // AccountInfo is generated from the Flashduty OpenAPI schema. @@ -2271,53 +2271,6 @@ type EventItem struct { UsageMetadata map[string]any `json:"usage_metadata" toon:"usage_metadata"` } -// ExportLine is generated from the Flashduty OpenAPI schema. -type ExportLine struct { - // Account id (on session_meta). - AccountID int64 `json:"account_id" toon:"account_id"` - // Dispatched subagent name (on subagent_dispatch). - AgentName string `json:"agent_name" toon:"agent_name"` - // Agent app (on session_meta). - AppName string `json:"app_name" toon:"app_name"` - // Child session id created by the dispatch (on subagent_dispatch). - ChildSessionID string `json:"child_session_id" toon:"child_session_id"` - // Text content of the line (messages, answers, errors). - Content string `json:"content" toon:"content"` - // Call duration in milliseconds. - DurationMs int64 `json:"duration_ms" toon:"duration_ms"` - // RFC3339 end timestamp; stamped on llm_call/tool_call/session_meta. - EndedAt string `json:"ended_at" toon:"ended_at"` - // Error detail when a call failed. - Error string `json:"error" toon:"error"` - // Tool call input arguments (on tool_call). - Input map[string]any `json:"input" toon:"input"` - // Byte size of the tool input. - InputBytes int64 `json:"input_bytes" toon:"input_bytes"` - // Chat model provider key; on session_meta and llm_call. - Model string `json:"model" toon:"model"` - // Tool name (on tool_call). - Name string `json:"name" toon:"name"` - // Tool call output (on tool_call response side). - Output string `json:"output" toon:"output"` - // Byte size of the tool output. - OutputBytes int64 `json:"output_bytes" toon:"output_bytes"` - // Parent session id for child sessions (on session_meta). - ParentSessionID string `json:"parent_session_id" toon:"parent_session_id"` - // 1-based monotonic sequence within the session (absent on session_meta). - Seq int64 `json:"seq" toon:"seq"` - // Session id (on session_meta). - SessionID string `json:"session_id" toon:"session_id"` - // RFC3339 start timestamp (session_meta uses session.created_at). - StartedAt string `json:"started_at" toon:"started_at"` - // Tool result status, e.g. ok or error. - Status string `json:"status" toon:"status"` - // RFC3339 timestamp of the event. - TS string `json:"ts" toon:"ts"` - // Line discriminator. - Type string `json:"type" toon:"type"` - Usage ExportUsage `json:"usage" toon:"usage"` -} - // ExportStatusPageSubscribersRequest is generated from the Flashduty OpenAPI schema. type ExportStatusPageSubscribersRequest struct { // Optional component IDs to filter subscribers by. @@ -2326,18 +2279,6 @@ type ExportStatusPageSubscribersRequest struct { PageID int64 `json:"page_id,omitempty" toon:"page_id,omitempty"` } -// ExportUsage is generated from the Flashduty OpenAPI schema. -type ExportUsage struct { - // Tokens written to the prompt cache. - CacheCreation int64 `json:"cache_creation" toon:"cache_creation"` - // Tokens served from the prompt cache. - CacheRead int64 `json:"cache_read" toon:"cache_read"` - // Prompt (input) tokens for the call. - InputTokens int64 `json:"input_tokens" toon:"input_tokens"` - // Generated (output) tokens for the call. - OutputTokens int64 `json:"output_tokens" toon:"output_tokens"` -} - // ExportedStatusPageSubscriberItem is generated from the Flashduty OpenAPI schema. type ExportedStatusPageSubscriberItem struct { // Whether the subscriber is subscribed to all components. @@ -3544,170 +3485,174 @@ type ListWebhookHistoryResponse struct { // McpServerCreateRequest is generated from the Flashduty OpenAPI schema. type McpServerCreateRequest struct { - // Command-line arguments for the stdio executable. + // Command arguments (stdio transport). Args []string `json:"args,omitempty" toon:"args,omitempty"` - // Credential model; defaults to shared. + // Authentication mode: shared (default), per_user_secret, or per_user_oauth. AuthMode string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` - // Per-call timeout in seconds. + // Tool-call timeout in seconds. 0 = default (60s). CallTimeout int64 `json:"call_timeout,omitempty" toon:"call_timeout,omitempty"` - // Executable to launch for stdio transport. + // Executable command (stdio transport). Command string `json:"command,omitempty" toon:"command,omitempty"` - // Connection timeout in seconds. + // Connection timeout in seconds. 0 = default (10s). ConnectTimeout int64 `json:"connect_timeout,omitempty" toon:"connect_timeout,omitempty"` - // What this MCP server provides. + // Server description. Description string `json:"description,omitempty" toon:"description,omitempty"` - // Environment variables for the stdio process. + // Environment variables (stdio transport). Env map[string]string `json:"env,omitempty" toon:"env,omitempty"` - // HTTP headers sent to the remote endpoint. + // HTTP headers (sse / streamable-http). Headers map[string]string `json:"headers,omitempty" toon:"headers,omitempty"` - // OAuth metadata JSON; reserved for OAuth-based auth. + // JSON OAuth metadata; reserved for per_user_oauth. OauthMetadata string `json:"oauth_metadata,omitempty" toon:"oauth_metadata,omitempty"` - // JSON schema of the per-user secret; required when auth_mode is per_user_secret. + // JSON secret schema; required when auth_mode=per_user_secret. SecretSchema string `json:"secret_schema,omitempty" toon:"secret_schema,omitempty"` - // Display name of the server. + // MCP server name, unique within the account. ServerName string `json:"server_name,omitempty" toon:"server_name,omitempty"` - // Initial lifecycle state of the server. + // Marketplace template name when created from a connector template. + SourceTemplateName string `json:"source_template_name,omitempty" toon:"source_template_name,omitempty"` + // Initial status. Status string `json:"status,omitempty" toon:"status,omitempty"` - // Owning team for the new server; 0 for account scope. + // Team scope: 0 = account-wide; >0 = team. TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` - // Transport used to reach the server. + // Transport protocol. Transport string `json:"transport,omitempty" toon:"transport,omitempty"` - // Endpoint URL for sse or streamable-http transport. + // Server URL (sse / streamable-http transport). URL string `json:"url,omitempty" toon:"url,omitempty"` } // McpServerDeleteRequest is generated from the Flashduty OpenAPI schema. type McpServerDeleteRequest struct { - // Identifier of the server to delete. + // Target MCP server ID. ServerID string `json:"server_id,omitempty" toon:"server_id,omitempty"` } // McpServerGetRequest is generated from the Flashduty OpenAPI schema. type McpServerGetRequest struct { - // Identifier of the server to fetch. + // Target MCP server ID. ServerID string `json:"server_id,omitempty" toon:"server_id,omitempty"` } // McpServerItem is generated from the Flashduty OpenAPI schema. type McpServerItem struct { - // Owning account. + // Owning account ID. AccountID int64 `json:"account_id" toon:"account_id"` - // LLM-generated description, preferred over description when present. + // LLM-generated description, preferred over `description` when present. AIDescription string `json:"ai_description" toon:"ai_description"` - // Command-line arguments for the stdio executable. + // Command arguments (stdio transport). Args []string `json:"args" toon:"args"` - // Credential model: shared, per_user_secret, or per_user_oauth. + // Authentication mode. AuthMode string `json:"auth_mode" toon:"auth_mode"` - // Per-call timeout in seconds. + // Tool-call timeout in seconds (0 = server default, 60s). CallTimeout int64 `json:"call_timeout" toon:"call_timeout"` - // Whether the calling member may edit or delete this resource. + // Whether the caller may edit this server. CanEdit bool `json:"can_edit" toon:"can_edit"` - // Executable launched for stdio transport. + // Executable command (stdio transport only). Command string `json:"command" toon:"command"` - // Connection timeout in seconds. + // Connection timeout in seconds (0 = server default, 10s). ConnectTimeout int64 `json:"connect_timeout" toon:"connect_timeout"` - // Creation time as a Unix timestamp in milliseconds. + // Creation time. Unix timestamp in milliseconds. CreatedAt TimestampMilli `json:"created_at" toon:"created_at"` - // Member who created this resource. + // Member ID that created the server. CreatedBy int64 `json:"created_by" toon:"created_by"` - // What this MCP server provides. + // Server description. Description string `json:"description" toon:"description"` - // Environment variables passed to the stdio process. + // Environment variables (stdio transport). Secret values are masked. Env map[string]string `json:"env" toon:"env"` - // HTTP headers sent to the remote endpoint; secret values are masked. + // HTTP headers (sse / streamable-http). Secret values are masked. Headers map[string]string `json:"headers" toon:"headers"` - // Tool-probe failure message; present when the live probe failed. + // Error message when the live tool list failed. ListError string `json:"list_error" toon:"list_error"` - // OAuth metadata JSON. + // JSON-encoded OAuth metadata (per_user_oauth mode). OauthMetadata string `json:"oauth_metadata" toon:"oauth_metadata"` // Outbound proxy URL used to reach the server. ProxyURL string `json:"proxy_url" toon:"proxy_url"` - // JSON schema of the per-user secret. + // JSON-encoded secret schema (per_user_secret mode). SecretSchema string `json:"secret_schema" toon:"secret_schema"` - // Unique identifier of the MCP server. + // Unique MCP server ID (prefix `mcp_`). ServerID string `json:"server_id" toon:"server_id"` - // Display name of the MCP server. + // MCP server name, unique within the account. ServerName string `json:"server_name" toon:"server_name"` - // Whether the server is active and usable by agents. + // Marketplace template this connector was installed from; empty for user-authored. + SourceTemplateName string `json:"source_template_name" toon:"source_template_name"` + // Server status. Status string `json:"status" toon:"status"` - // Owning team; 0 means account scope. + // Team scope: 0 = account-wide; >0 = the owning team. TeamID int64 `json:"team_id" toon:"team_id"` - // Number of tools discovered on the server. + // Number of tools in the live list. ToolCount int64 `json:"tool_count" toon:"tool_count"` - // Live tool catalogue; populated only by get and test. + // Live tool list; populated by the get/test endpoints. Tools []McpToolInfo `json:"tools" toon:"tools"` - // Transport used to reach the server. + // Transport protocol. Transport string `json:"transport" toon:"transport"` - // Last-update time as a Unix timestamp in milliseconds. + // Last update time. Unix timestamp in milliseconds. UpdatedAt TimestampMilli `json:"updated_at" toon:"updated_at"` - // Endpoint URL for sse or streamable-http transport. + // Server URL (sse / streamable-http transport). URL string `json:"url" toon:"url"` } // McpServerListRequest is generated from the Flashduty OpenAPI schema. type McpServerListRequest struct { ListOptions - // Include account-scoped rows alongside team-scoped ones; defaults to true. - IncludeAccount bool `json:"include_account,omitempty" toon:"include_account,omitempty"` - // Restrict results to resources owned by these teams; intersected with the caller's visible set. + // Include account-scoped (team_id=0) rows. Defaults to true. + IncludeAccount *bool `json:"include_account,omitempty" toon:"include_account,omitempty"` + // Filter to these team IDs; empty = the caller's visible set. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } // McpServerListResponse is generated from the Flashduty OpenAPI schema. type McpServerListResponse struct { - // MCP servers on the current page. + // MCP servers on this page. Servers []McpServerItem `json:"servers" toon:"servers"` - // Total number of servers matching the filters. + // Total number of matching servers. Total int64 `json:"total" toon:"total"` } // McpServerStatusRequest is generated from the Flashduty OpenAPI schema. type McpServerStatusRequest struct { - // Identifier of the target server. + // Target MCP server ID. ServerID string `json:"server_id,omitempty" toon:"server_id,omitempty"` } // McpServerUpdateRequest is generated from the Flashduty OpenAPI schema. type McpServerUpdateRequest struct { - // New stdio arguments. + // Command arguments (stdio transport). Args []string `json:"args,omitempty" toon:"args,omitempty"` - // New credential model. + // Authentication mode: shared (default), per_user_secret, or per_user_oauth. AuthMode string `json:"auth_mode,omitempty" toon:"auth_mode,omitempty"` - // New per-call timeout in seconds. + // Tool-call timeout in seconds. 0 = default (60s). CallTimeout int64 `json:"call_timeout,omitempty" toon:"call_timeout,omitempty"` - // New stdio executable. + // Executable command (stdio transport). Command string `json:"command,omitempty" toon:"command,omitempty"` - // New connection timeout in seconds. + // Connection timeout in seconds. 0 = default (10s). ConnectTimeout int64 `json:"connect_timeout,omitempty" toon:"connect_timeout,omitempty"` // New description. Description string `json:"description,omitempty" toon:"description,omitempty"` - // New stdio environment variables. + // Environment variables (stdio transport). Env map[string]string `json:"env,omitempty" toon:"env,omitempty"` - // New HTTP headers for the remote endpoint. + // HTTP headers (sse / streamable-http). Headers map[string]string `json:"headers,omitempty" toon:"headers,omitempty"` - // New OAuth metadata JSON. + // JSON OAuth metadata; reserved for per_user_oauth. OauthMetadata string `json:"oauth_metadata,omitempty" toon:"oauth_metadata,omitempty"` - // New per-user secret JSON schema. + // JSON secret schema; required when auth_mode=per_user_secret. SecretSchema string `json:"secret_schema,omitempty" toon:"secret_schema,omitempty"` - // Identifier of the server to update. + // Target MCP server ID. ServerID string `json:"server_id,omitempty" toon:"server_id,omitempty"` - // New display name. + // New name. ServerName string `json:"server_name,omitempty" toon:"server_name,omitempty"` - // Reassign the server to this team; omit to leave unchanged, 0 for account scope. - TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` - // New transport for the server. + // Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged. + TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` + // Transport protocol. Transport string `json:"transport,omitempty" toon:"transport,omitempty"` - // New endpoint URL for remote transports. + // Server URL (sse / streamable-http transport). URL string `json:"url,omitempty" toon:"url,omitempty"` } // McpToolInfo is generated from the Flashduty OpenAPI schema. type McpToolInfo struct { - // What the tool does. + // Tool description. Description string `json:"description" toon:"description"` - // JSON schema of the tool's input arguments. - InputSchema any `json:"input_schema" toon:"input_schema"` - // Tool name as advertised by the server. + // JSON Schema describing the tool's input parameters. + InputSchema map[string]any `json:"input_schema" toon:"input_schema"` + // Tool name. Name string `json:"name" toon:"name"` } @@ -5435,23 +5380,29 @@ type ScheduleUpsertRequest struct { TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } +// SessionDeleteRequest is generated from the Flashduty OpenAPI schema. +type SessionDeleteRequest struct { + // Target session ID. + SessionID string `json:"session_id,omitempty" toon:"session_id,omitempty"` +} + // SessionExportRequest is generated from the Flashduty OpenAPI schema. type SessionExportRequest struct { // When true, each subagent_dispatch line is followed by the child session's full event stream, bracketed by its own session_meta. Defaults to false. IncludeSubagents bool `json:"include_subagents,omitempty" toon:"include_subagents,omitempty"` - // Session identifier to export. + // Target session ID. SessionID string `json:"session_id,omitempty" toon:"session_id,omitempty"` } // SessionGetRequest is generated from the Flashduty OpenAPI schema. type SessionGetRequest struct { - // Alias for num_recent_events; takes precedence when both are set. + // Page size for events; takes precedence over `num_recent_events`. 0 uses the server default (100). Limit int64 `json:"limit,omitempty" toon:"limit,omitempty"` - // Number of most-recent events to return; 0 uses the server default. + // Legacy page size: number of most-recent events to return. Superseded by `limit` when both are set; 0 uses the server default (100). NumRecentEvents int64 `json:"num_recent_events,omitempty" toon:"num_recent_events,omitempty"` - // Opaque keyset cursor from a previous response's search_after_ctx, to page backward through older events. + // Opaque keyset cursor from a previous response; pass it back to fetch the next older page. SearchAfterCtx string `json:"search_after_ctx,omitempty" toon:"search_after_ctx,omitempty"` - // Session identifier. + // Target session ID. SessionID string `json:"session_id,omitempty" toon:"session_id,omitempty"` } @@ -5524,21 +5475,21 @@ type SessionListRequest struct { ListOptions // Agent app whose sessions to list. AppName string `json:"app_name,omitempty" toon:"app_name,omitempty"` - // Ascending sort when true; defaults to false (descending). Only honored when orderby is set. + // Ascending order when true; applies only when `orderby` is set. Asc bool `json:"asc,omitempty" toon:"asc,omitempty"` - // Restrict to sessions produced by these entry surfaces. Empty returns every kind. + // Restrict to sessions produced by these surfaces; empty returns every kind. EntryKinds []string `json:"entry_kinds,omitempty" toon:"entry_kinds,omitempty"` - // Include subagent (child) sessions in the result; defaults to false. + // Include subagent-dispatched sessions in the list. IncludeSubagentSessions bool `json:"include_subagent_sessions,omitempty" toon:"include_subagent_sessions,omitempty"` - // Case-insensitive substring match against session name. + // Filter by session-name keyword. Keyword string `json:"keyword,omitempty" toon:"keyword,omitempty"` - // Sort column. + // Sort field. Orderby string `json:"orderby,omitempty" toon:"orderby,omitempty"` - // Visibility scope: all (own + member-of-team rows, the default), personal (own only), or team (member teams only). + // Visibility scope: all (own + member-of-team rows, default), personal, or team. Scope string `json:"scope,omitempty" toon:"scope,omitempty"` - // Archive bucket: active (default, not archived), archived, or all. + // Archive bucket: active (default) returns un-archived, archived returns archived, all returns both. Status string `json:"status,omitempty" toon:"status,omitempty"` - // Optional explicit team filter; intersected with the caller's visible set / scope. + // Optional explicit team filter; intersects with `scope`. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } @@ -5592,102 +5543,108 @@ type SilenceRuleItem struct { // SkillDeleteRequest is generated from the Flashduty OpenAPI schema. type SkillDeleteRequest struct { - // Identifier of the skill to delete. - SkillID string `json:"skill_id,omitempty" toon:"skill_id,omitempty"` -} - -// SkillDownloadRequest is generated from the Flashduty OpenAPI schema. -type SkillDownloadRequest struct { - // Identifier of the skill to download. + // Target skill ID. SkillID string `json:"skill_id,omitempty" toon:"skill_id,omitempty"` } // SkillGetRequest is generated from the Flashduty OpenAPI schema. type SkillGetRequest struct { - // Identifier of the skill to fetch. + // Target skill ID. SkillID string `json:"skill_id,omitempty" toon:"skill_id,omitempty"` } // SkillItem is generated from the Flashduty OpenAPI schema. type SkillItem struct { - // Owning account. + // Owning account ID. AccountID int64 `json:"account_id" toon:"account_id"` - // Author declared in the skill frontmatter. + // Skill author. Author string `json:"author" toon:"author"` - // Whether the calling member may edit or delete this resource. + // Whether the caller may edit this skill. CanEdit bool `json:"can_edit" toon:"can_edit"` - // SHA-256 checksum of the skill's zip package. + // SHA-256 checksum of the skill zip. Checksum string `json:"checksum" toon:"checksum"` - // Full SKILL.md body; omitted in list responses. + // Full SKILL.md content. Omitted in list responses. Content string `json:"content" toon:"content"` - // Install response only: true for a fresh install, false for an in-place upsert. + // Set only on install-from-session responses: true = fresh install, false = in-place update. Created bool `json:"created" toon:"created"` - // Creation time as a Unix timestamp in milliseconds. + // Creation time. Unix timestamp in milliseconds. CreatedAt TimestampMilli `json:"created_at" toon:"created_at"` - // Member who created this resource. + // Member ID that created the skill. CreatedBy int64 `json:"created_by" toon:"created_by"` - // What the skill does and when the agent should use it. + // Human-readable description from the SKILL.md frontmatter. Description string `json:"description" toon:"description"` - // A marketplace-sourced skill has been edited locally; auto-update skips it. + // True when a marketplace-sourced skill was edited locally (auto-update skips it). IsModified bool `json:"is_modified" toon:"is_modified"` - // License declared in the skill frontmatter. + // Skill license. License string `json:"license" toon:"license"` - // Object-storage key of the skill's zip package. + // Object-storage key of the skill zip. S3Key string `json:"s3_key" toon:"s3_key"` - // Unique identifier of the skill. + // Unique skill ID (prefix `skill_`). SkillID string `json:"skill_id" toon:"skill_id"` - // Name of the skill, parsed from its SKILL.md frontmatter. + // Skill name, unique within the account. SkillName string `json:"skill_name" toon:"skill_name"` - // Marketplace template this skill was installed from, if any. + // Marketplace template this skill was installed from; empty for user-authored. SourceTemplateName string `json:"source_template_name" toon:"source_template_name"` - // Marketplace template version captured at install time. + // Template version at install time. SourceTemplateVersion string `json:"source_template_version" toon:"source_template_version"` - // Whether the skill is active and loadable by agents. + // Skill status. Status string `json:"status" toon:"status"` - // Tags declared in the skill frontmatter. + // Tags parsed from the frontmatter. Tags []string `json:"tags" toon:"tags"` - // Owning team; 0 means account scope. + // Team scope: 0 = account-wide; >0 = the owning team. TeamID int64 `json:"team_id" toon:"team_id"` - // Tools the skill requires, declared in its frontmatter. + // Required tools (builtin or `mcp:server/tool`). Tools []string `json:"tools" toon:"tools"` - // A newer marketplace template version exists for this skill. + // True when the marketplace has a newer template version. UpdateAvailable bool `json:"update_available" toon:"update_available"` - // Last-update time as a Unix timestamp in milliseconds. + // Last update time. Unix timestamp in milliseconds. UpdatedAt TimestampMilli `json:"updated_at" toon:"updated_at"` - // Skill version string from its frontmatter. + // Skill version from the frontmatter. Version string `json:"version" toon:"version"` } // SkillListRequest is generated from the Flashduty OpenAPI schema. type SkillListRequest struct { ListOptions - // Include account-scoped rows alongside team-scoped ones; defaults to true. - IncludeAccount bool `json:"include_account,omitempty" toon:"include_account,omitempty"` - // Restrict results to resources owned by these teams; intersected with the caller's visible set. + // Include account-scoped (team_id=0) rows. Defaults to true. + IncludeAccount *bool `json:"include_account,omitempty" toon:"include_account,omitempty"` + // Filter to these team IDs; empty = the caller's visible set. TeamIDs []int64 `json:"team_ids,omitempty" toon:"team_ids,omitempty"` } // SkillListResponse is generated from the Flashduty OpenAPI schema. type SkillListResponse struct { - // Skills on the current page. + // Skills on this page. Skills []SkillItem `json:"skills" toon:"skills"` - // Total number of skills matching the filters. + // Total number of matching skills. Total int64 `json:"total" toon:"total"` } // SkillStatusRequest is generated from the Flashduty OpenAPI schema. type SkillStatusRequest struct { - // Identifier of the target skill. + // Target skill ID. SkillID string `json:"skill_id,omitempty" toon:"skill_id,omitempty"` } // SkillUpdateRequest is generated from the Flashduty OpenAPI schema. type SkillUpdateRequest struct { - // New description for the skill. + // New description. Description string `json:"description,omitempty" toon:"description,omitempty"` - // Identifier of the skill to update. + // Target skill ID. + SkillID string `json:"skill_id,omitempty" toon:"skill_id,omitempty"` + // Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged. + TeamID *int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` +} + +// SkillUploadRequest is generated from the Flashduty OpenAPI schema. +type SkillUploadRequest struct { + // Skill archive (.skill / .zip / .tar.gz / .tgz). Max 100MB. + File string `json:"file,omitempty" toon:"file,omitempty"` + // When true, overwrite an existing same-name skill. + Replace bool `json:"replace,omitempty" toon:"replace,omitempty"` + // When replacing a specific skill, its skill ID. SkillID string `json:"skill_id,omitempty" toon:"skill_id,omitempty"` - // Reassign the skill to this team; omit to leave unchanged, 0 for account scope. + // Team scope for the new skill: 0 = account-wide. TeamID int64 `json:"team_id,omitempty" toon:"team_id,omitempty"` } diff --git a/openapi/openapi.en.json b/openapi/openapi.en.json index d67f309..084e110 100644 --- a/openapi/openapi.en.json +++ b/openapi/openapi.en.json @@ -20422,7 +20422,7 @@ "total": 1, "skills": [ { - "skill_id": "skl-7f3a9c21b8e0", + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", "account_id": 10023, "team_id": 0, "skill_name": "k8s-triage", @@ -20433,6 +20433,10 @@ "triage" ], "author": "sre-team", + "tools": [ + "bash", + "mcp:prometheus/query" + ], "status": "enabled", "created_by": 80011, "created_at": 1716960000000, @@ -20481,7 +20485,7 @@ "post": { "operationId": "skill-read-get", "summary": "Get skill detail", - "description": "Return the full configuration and SKILL.md body of a single skill by ID.", + "description": "Get one skill including its full SKILL.md content.", "tags": [ "AI SRE/Skills" ], @@ -20520,7 +20524,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "skill_id": "skl-7f3a9c21b8e0", + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", "account_id": 10023, "team_id": 0, "skill_name": "k8s-triage", @@ -20531,6 +20535,10 @@ "triage" ], "author": "sre-team", + "tools": [ + "bash", + "mcp:prometheus/query" + ], "status": "enabled", "created_by": 80011, "created_at": 1716960000000, @@ -20538,7 +20546,7 @@ "can_edit": true, "update_available": false, "is_modified": false, - "content": "---\nname: k8s-triage\n---\nDiagnose unhealthy workloads..." + "content": "---\nname: k8s-triage\ndescription: ...\n---\n# Triage steps" } } } @@ -20565,7 +20573,7 @@ "$ref": "#/components/schemas/SkillGetRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m" } } } @@ -20576,7 +20584,7 @@ "post": { "operationId": "skill-write-update", "summary": "Update skill", - "description": "Edit a skill's description or reassign its owning team.", + "description": "Update a skill's description or reassign its team scope.", "tags": [ "AI SRE/Skills" ], @@ -20586,7 +20594,7 @@ } ], "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- Only skills the caller may edit can be updated; others return AccessDenied.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only `description` and `team_id` are editable; the skill body is changed by re-uploading.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/skills/skill-write-update", "metadata": { "sidebarTitle": "Update skill" @@ -20615,17 +20623,21 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "skill_id": "skl-7f3a9c21b8e0", + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", "account_id": 10023, "team_id": 0, "skill_name": "k8s-triage", - "description": "Diagnose unhealthy Kubernetes workloads.", + "description": "Updated triage runbook.", "version": "1.2.0", "tags": [ "kubernetes", "triage" ], "author": "sre-team", + "tools": [ + "bash", + "mcp:prometheus/query" + ], "status": "enabled", "created_by": 80011, "created_at": 1716960000000, @@ -20644,6 +20656,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -20659,8 +20674,8 @@ "$ref": "#/components/schemas/SkillUpdateRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0", - "description": "Diagnose unhealthy Kubernetes workloads." + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", + "description": "Updated triage runbook." } } } @@ -20671,7 +20686,7 @@ "post": { "operationId": "skill-write-delete", "summary": "Delete skill", - "description": "Permanently remove a skill so agents can no longer load it.", + "description": "Delete a skill by ID.", "tags": [ "AI SRE/Skills" ], @@ -20681,7 +20696,7 @@ } ], "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- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/skills/skill-write-delete", "metadata": { "sidebarTitle": "Delete skill" @@ -20702,14 +20717,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -20720,6 +20736,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -20735,7 +20754,7 @@ "$ref": "#/components/schemas/SkillDeleteRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m" } } } @@ -20746,7 +20765,7 @@ "post": { "operationId": "skill-write-upload", "summary": "Upload skill", - "description": "Upload a skill zip package and register it as a new account or team skill.", + "description": "Upload a skill archive (.skill/.zip/.tar.gz/.tgz) to create or replace a skill.", "tags": [ "AI SRE/Skills" ], @@ -20756,7 +20775,7 @@ } ], "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- Request is `multipart/form-data` with a `file` part (the zip) and an optional `team_id` field, not JSON.\n- Duplicate skill names return InvalidParameter.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **30 requests/minute**; **3 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Send as `multipart/form-data` with a `file` part. Max archive size is 100MB.\n- Set `replace=true` to overwrite an existing same-name skill.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/skills/skill-write-upload", "metadata": { "sidebarTitle": "Upload skill" @@ -20785,7 +20804,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "skill_id": "skl-7f3a9c21b8e0", + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", "account_id": 10023, "team_id": 0, "skill_name": "k8s-triage", @@ -20796,13 +20815,18 @@ "triage" ], "author": "sre-team", + "tools": [ + "bash", + "mcp:prometheus/query" + ], "status": "enabled", "created_by": 80011, "created_at": 1716960000000, "updated_at": 1717046400000, "can_edit": true, "update_available": false, - "is_modified": false + "is_modified": false, + "created": true } } } @@ -20814,93 +20838,8 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "Skill zip package to upload." - }, - "team_id": { - "type": "integer", - "format": "int64", - "description": "Owning team for the new skill; 0 for account scope." - } - }, - "required": [ - "file" - ] - } - } - } - } - } - }, - "/safari/skill/download": { - "post": { - "operationId": "skill-read-download", - "summary": "Download skill", - "description": "Download the original zip package of a skill as a binary attachment.", - "tags": [ - "AI SRE/Skills" - ], - "security": [ - { - "AppKeyAuth": [] - } - ], - "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- Responds with `application/zip` bytes and a `Content-Disposition` attachment header, not the JSON envelope.\n", - "href": "/en/api-reference/ai-sre/skills/skill-read-download", - "metadata": { - "sidebarTitle": "Download skill" - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/ResponseEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "type": "string", - "format": "binary", - "description": "Raw zip bytes (not wrapped in the JSON envelope)." - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" + "403": { + "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" @@ -20912,12 +20851,13 @@ "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/SkillDownloadRequest" + "$ref": "#/components/schemas/SkillUploadRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "team_id": 0, + "replace": false } } } @@ -20928,7 +20868,7 @@ "post": { "operationId": "skill-read-enable", "summary": "Enable skill", - "description": "Activate a disabled skill so agents can load it at session start.", + "description": "Enable a disabled skill so the agent can load it.", "tags": [ "AI SRE/Skills" ], @@ -20938,7 +20878,7 @@ } ], "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- Only disabled skills can be enabled; an already-enabled skill returns InvalidParameter.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only a `disabled` skill can be enabled; otherwise returns InvalidParameter.\n", "href": "/en/api-reference/ai-sre/skills/skill-read-enable", "metadata": { "sidebarTitle": "Enable skill" @@ -20959,14 +20899,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -20977,6 +20918,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -20992,7 +20936,7 @@ "$ref": "#/components/schemas/SkillStatusRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m" } } } @@ -21003,7 +20947,7 @@ "post": { "operationId": "skill-write-disable", "summary": "Disable skill", - "description": "Deactivate an enabled skill so agents no longer load it.", + "description": "Disable an enabled skill so the agent stops loading it.", "tags": [ "AI SRE/Skills" ], @@ -21013,7 +20957,7 @@ } ], "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- Only enabled skills can be disabled; an already-disabled skill returns InvalidParameter.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Skill Manage** (`ai-sre`) |\n\n## Usage\n\n- Only an `enabled` skill can be disabled; otherwise returns InvalidParameter.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/skills/skill-write-disable", "metadata": { "sidebarTitle": "Disable skill" @@ -21034,14 +20978,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -21052,6 +20997,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21067,7 +21015,7 @@ "$ref": "#/components/schemas/SkillStatusRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m" } } } @@ -21078,7 +21026,7 @@ "post": { "operationId": "mcp-read-server-list", "summary": "List MCP servers", - "description": "List configured MCP servers visible to the caller across account and team scopes, with pagination.", + "description": "List MCP servers visible to the caller across account and team scopes, with pagination.", "tags": [ "AI SRE/MCP servers" ], @@ -21088,7 +21036,7 @@ } ], "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", + "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- The live tool list is not included; fetch a single server to probe its tools.\n", "href": "/en/api-reference/ai-sre/mcp-servers/mcp-read-server-list", "metadata": { "sidebarTitle": "List MCP servers" @@ -21120,25 +21068,28 @@ "total": 1, "servers": [ { - "server_id": "mcp-2b5e8d14a7c9", + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", "account_id": 10023, "team_id": 0, "can_edit": true, - "server_name": "GitHub Tools", - "description": "Read issues and pull requests from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, + "server_name": "prometheus", + "description": "Query Prometheus metrics and alerts.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", "status": "enabled", "connect_timeout": 10, - "call_timeout": 30, - "tool_count": 12, + "call_timeout": 60, + "tool_count": 2, + "tools": [ + { + "name": "query", + "description": "Run a PromQL instant query." + }, + { + "name": "query_range", + "description": "Run a PromQL range query." + } + ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -21184,7 +21135,7 @@ "post": { "operationId": "mcp-write-server-create", "summary": "Create MCP server", - "description": "Register a new MCP server the agent can call tools through.", + "description": "Register a new MCP server (connector) on the account.", "tags": [ "AI SRE/MCP servers" ], @@ -21194,7 +21145,7 @@ } ], "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- `transport` must be one of stdio, sse, or streamable-http; other values return InvalidParameter.\n- Duplicate server names return InvalidParameter.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- `command`/`args`/`env` apply to `stdio`; `url`/`headers` apply to `sse`/`streamable-http`.\n- Server name must be unique within the account; duplicates return InvalidParameter.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-create", "metadata": { "sidebarTitle": "Create MCP server" @@ -21223,25 +21174,28 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "server_id": "mcp-2b5e8d14a7c9", + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", "account_id": 10023, "team_id": 0, "can_edit": true, - "server_name": "GitHub Tools", - "description": "Read issues and pull requests from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, + "server_name": "prometheus", + "description": "Query Prometheus metrics and alerts.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", "status": "enabled", "connect_timeout": 10, - "call_timeout": 30, - "tool_count": 12, + "call_timeout": 60, + "tool_count": 2, + "tools": [ + { + "name": "query", + "description": "Run a PromQL instant query." + }, + { + "name": "query_range", + "description": "Run a PromQL range query." + } + ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -21257,6 +21211,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21272,19 +21229,11 @@ "$ref": "#/components/schemas/MCPServerCreateRequest" }, "example": { - "server_name": "GitHub Tools", - "description": "Read issues and pull requests from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, - "status": "enabled", - "team_id": 0 + "server_name": "prometheus", + "description": "Query Prometheus metrics and alerts.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", + "status": "enabled" } } } @@ -21295,7 +21244,7 @@ "post": { "operationId": "mcp-read-server-get", "summary": "Get MCP server detail", - "description": "Return the full configuration of a single MCP server, with a live tool catalogue.", + "description": "Get one MCP server and run a live probe of its tool list.", "tags": [ "AI SRE/MCP servers" ], @@ -21305,7 +21254,7 @@ } ], "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- A live tool probe runs on this call; failures populate `list_error` rather than failing the request.\n", + "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- The detail call live-probes tools; on failure `list_error` is set and the request still succeeds.\n", "href": "/en/api-reference/ai-sre/mcp-servers/mcp-read-server-get", "metadata": { "sidebarTitle": "Get MCP server detail" @@ -21334,39 +21283,32 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "server_id": "mcp-2b5e8d14a7c9", + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", "account_id": 10023, "team_id": 0, "can_edit": true, - "server_name": "GitHub Tools", - "description": "Read issues and pull requests from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, + "server_name": "prometheus", + "description": "Query Prometheus metrics and alerts.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", "status": "enabled", "connect_timeout": 10, - "call_timeout": 30, - "tool_count": 12, - "auth_mode": "shared", - "created_by": 80011, - "created_at": 1716960000000, - "updated_at": 1717046400000, + "call_timeout": 60, + "tool_count": 2, "tools": [ { - "name": "list_issues", - "description": "List issues in a repository." + "name": "query", + "description": "Run a PromQL instant query." }, { - "name": "get_pull_request", - "description": "Fetch a pull request by number." + "name": "query_range", + "description": "Run a PromQL range query." } - ] + ], + "auth_mode": "shared", + "created_by": 80011, + "created_at": 1716960000000, + "updated_at": 1717046400000 } } } @@ -21393,7 +21335,7 @@ "$ref": "#/components/schemas/MCPServerGetRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9" + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1" } } } @@ -21404,7 +21346,7 @@ "post": { "operationId": "mcp-write-server-update", "summary": "Update MCP server", - "description": "Edit an MCP server's connection settings or reassign its owning team.", + "description": "Update an MCP server's configuration. Omit a field to leave it unchanged.", "tags": [ "AI SRE/MCP servers" ], @@ -21414,7 +21356,7 @@ } ], "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 MCP servers are read-only and cannot be modified.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Masked secret values in `env`/`headers` are preserved — sending the masked value back does not overwrite the stored secret.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-update", "metadata": { "sidebarTitle": "Update MCP server" @@ -21443,25 +21385,28 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "server_id": "mcp-2b5e8d14a7c9", + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", "account_id": 10023, "team_id": 0, "can_edit": true, - "server_name": "GitHub Tools", - "description": "Read issues, PRs, and commits from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, + "server_name": "prometheus", + "description": "Query Prometheus metrics, alerts, and rules.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", "status": "enabled", "connect_timeout": 10, - "call_timeout": 30, - "tool_count": 12, + "call_timeout": 60, + "tool_count": 2, + "tools": [ + { + "name": "query", + "description": "Run a PromQL instant query." + }, + { + "name": "query_range", + "description": "Run a PromQL range query." + } + ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -21477,6 +21422,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21492,8 +21440,8 @@ "$ref": "#/components/schemas/MCPServerUpdateRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9", - "description": "Read issues, PRs, and commits from GitHub." + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", + "description": "Query Prometheus metrics, alerts, and rules." } } } @@ -21504,7 +21452,7 @@ "post": { "operationId": "mcp-write-server-delete", "summary": "Delete MCP server", - "description": "Permanently remove an MCP server so agents can no longer use its tools.", + "description": "Delete an MCP server by ID.", "tags": [ "AI SRE/MCP servers" ], @@ -21514,7 +21462,7 @@ } ], "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 MCP servers are read-only and cannot be deleted.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-delete", "metadata": { "sidebarTitle": "Delete MCP server" @@ -21535,14 +21483,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -21553,6 +21502,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21568,7 +21520,7 @@ "$ref": "#/components/schemas/MCPServerDeleteRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9" + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1" } } } @@ -21579,7 +21531,7 @@ "post": { "operationId": "mcp-write-server-enable", "summary": "Enable MCP server", - "description": "Activate a disabled MCP server so agents can call its tools.", + "description": "Enable a disabled MCP server.", "tags": [ "AI SRE/MCP servers" ], @@ -21589,7 +21541,7 @@ } ], "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 MCP servers are read-only; an already-enabled server returns InvalidParameter.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-enable", "metadata": { "sidebarTitle": "Enable MCP server" @@ -21610,14 +21562,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -21628,6 +21581,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21643,7 +21599,7 @@ "$ref": "#/components/schemas/MCPServerStatusRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9" + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1" } } } @@ -21654,7 +21610,7 @@ "post": { "operationId": "mcp-write-server-disable", "summary": "Disable MCP server", - "description": "Deactivate an MCP server so agents stop calling its tools.", + "description": "Disable an enabled MCP server.", "tags": [ "AI SRE/MCP servers" ], @@ -21664,7 +21620,7 @@ } ], "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 MCP servers are read-only; an already-disabled server returns InvalidParameter.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **MCP Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/mcp-servers/mcp-write-server-disable", "metadata": { "sidebarTitle": "Disable MCP server" @@ -21685,14 +21641,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -21703,6 +21660,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21718,7 +21678,7 @@ "$ref": "#/components/schemas/MCPServerStatusRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9" + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1" } } } @@ -21729,7 +21689,7 @@ "post": { "operationId": "remote-agent-write-create", "summary": "Create A2A agent", - "description": "Register a new A2A remote agent the SRE agent can delegate tasks to.", + "description": "Register a new A2A remote agent from its agent-card URL.", "tags": [ "AI SRE/A2A agents" ], @@ -21739,7 +21699,7 @@ } ], "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- The agent card at `card_url` is fetched and validated; an unreachable card returns InvalidParameter.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- `card_url` must resolve to a valid agent card; an unreachable or invalid card returns InvalidParameter.\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-create", "metadata": { "sidebarTitle": "Create A2A agent" @@ -21768,7 +21728,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -21780,6 +21740,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21795,13 +21758,9 @@ "$ref": "#/components/schemas/A2AAgentCreateRequest" }, "example": { - "agent_name": "Network Diagnostics Agent", - "card_url": "https://agents.example.com/network-diag/.well-known/agent.json", - "description": "Runs traceroute and BGP-path analysis for network incidents.", + "agent_name": "deploy-bot", + "card_url": "https://agents.example.com/deploy-bot/card", "auth_type": "bearer", - "auth_config": { - "token": "secret" - }, "streaming": true, "team_id": 0 } @@ -21814,7 +21773,7 @@ "post": { "operationId": "remote-agent-read-list", "summary": "List A2A agents", - "description": "List registered A2A agents visible to the caller across account and team scopes, with pagination.", + "description": "List A2A agents visible to the caller across account and team scopes, with pagination.", "tags": [ "AI SRE/A2A agents" ], @@ -21824,7 +21783,7 @@ } ], "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", + "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- Pagination uses `offset`/`limit` (not `p`/`limit`).\n", "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-read-list", "metadata": { "sidebarTitle": "List A2A agents" @@ -21855,30 +21814,27 @@ "data": { "items": [ { - "agent_id": "a2a_9d4c1f60b3a2", + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D", "account_id": 10023, "team_id": 0, "can_edit": true, - "agent_name": "Network Diagnostics Agent", - "description": "Runs traceroute and BGP-path analysis for network incidents.", - "card_url": "https://agents.example.com/network-diag/.well-known/agent.json", + "agent_name": "deploy-bot", + "description": "Remote agent that inspects deployment pipelines.", + "card_url": "https://agents.example.com/deploy-bot/card", "auth_type": "bearer", - "auth_config": { - "token": "secret" - }, "streaming": true, "status": "enabled", - "agent_card_name": "network-diag", + "agent_card_name": "Deploy Bot", "agent_card_skills": [ - "traceroute", - "bgp-analysis" + "rollback", + "diff" ], "card_resolve_timeout": 10, "task_timeout": 120, "auth_mode": "shared", "created_by": 80011, - "created_at": 1716960000, - "updated_at": 1717046400 + "created_at": 1716960000000, + "updated_at": 1717046400000 } ], "total": 1 @@ -21921,7 +21877,7 @@ "post": { "operationId": "remote-agent-read-get", "summary": "Get A2A agent detail", - "description": "Return the full configuration of a single A2A agent by ID.", + "description": "Get one A2A agent by ID.", "tags": [ "AI SRE/A2A agents" ], @@ -21960,30 +21916,27 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "agent_id": "a2a_9d4c1f60b3a2", + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D", "account_id": 10023, "team_id": 0, "can_edit": true, - "agent_name": "Network Diagnostics Agent", - "description": "Runs traceroute and BGP-path analysis for network incidents.", - "card_url": "https://agents.example.com/network-diag/.well-known/agent.json", + "agent_name": "deploy-bot", + "description": "Remote agent that inspects deployment pipelines.", + "card_url": "https://agents.example.com/deploy-bot/card", "auth_type": "bearer", - "auth_config": { - "token": "secret" - }, "streaming": true, "status": "enabled", - "agent_card_name": "network-diag", + "agent_card_name": "Deploy Bot", "agent_card_skills": [ - "traceroute", - "bgp-analysis" + "rollback", + "diff" ], "card_resolve_timeout": 10, "task_timeout": 120, "auth_mode": "shared", "created_by": 80011, - "created_at": 1716960000, - "updated_at": 1717046400 + "created_at": 1716960000000, + "updated_at": 1717046400000 } } } @@ -22010,7 +21963,7 @@ "$ref": "#/components/schemas/A2AAgentIDRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -22021,7 +21974,7 @@ "post": { "operationId": "remote-agent-write-update", "summary": "Update A2A agent", - "description": "Edit an A2A agent's card URL, auth, streaming flag, or owning team.", + "description": "Apply a partial update to an A2A agent. Omit a field to leave it unchanged.", "tags": [ "AI SRE/A2A agents" ], @@ -22031,7 +21984,7 @@ } ], "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- Omit a field to leave it unchanged; only fields present in the request are updated.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-update", "metadata": { "sidebarTitle": "Update A2A agent" @@ -22052,14 +22005,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -22070,6 +22024,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -22085,8 +22042,8 @@ "$ref": "#/components/schemas/A2AAgentUpdateRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2", - "description": "Runs traceroute, BGP, and DNS analysis for network incidents." + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D", + "description": "Inspects deployment pipelines and proposes rollbacks." } } } @@ -22097,7 +22054,7 @@ "post": { "operationId": "remote-agent-write-enable", "summary": "Enable A2A agent", - "description": "Activate a disabled A2A agent so the SRE agent can delegate to it.", + "description": "Enable a disabled A2A agent.", "tags": [ "AI SRE/A2A agents" ], @@ -22107,7 +22064,7 @@ } ], "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- An already-enabled agent returns InvalidParameter.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-enable", "metadata": { "sidebarTitle": "Enable A2A agent" @@ -22128,14 +22085,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -22146,6 +22104,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -22161,7 +22122,7 @@ "$ref": "#/components/schemas/A2AAgentIDRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -22172,7 +22133,7 @@ "post": { "operationId": "remote-agent-write-disable", "summary": "Disable A2A agent", - "description": "Deactivate an A2A agent so the SRE agent stops delegating to it.", + "description": "Disable an enabled A2A agent.", "tags": [ "AI SRE/A2A agents" ], @@ -22182,7 +22143,7 @@ } ], "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- An already-disabled agent returns InvalidParameter.\n- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-disable", "metadata": { "sidebarTitle": "Disable A2A agent" @@ -22203,14 +22164,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -22221,6 +22183,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -22236,7 +22201,7 @@ "$ref": "#/components/schemas/A2AAgentIDRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -22247,7 +22212,7 @@ "post": { "operationId": "remote-agent-write-delete", "summary": "Delete A2A agent", - "description": "Soft-delete an A2A agent registration so it can no longer be used.", + "description": "Soft-delete an A2A agent by ID.", "tags": [ "AI SRE/A2A agents" ], @@ -22257,7 +22222,7 @@ } ], "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- Every call is recorded in the account's audit log.\n", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Agent Manage** (`ai-sre`) |\n\n## Usage\n\n- Every call is recorded in the account audit log.\n", "href": "/en/api-reference/ai-sre/a2a-agents/remote-agent-write-delete", "metadata": { "sidebarTitle": "Delete A2A agent" @@ -22278,14 +22243,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "Always null on success." } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -22296,6 +22262,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -22311,7 +22280,7 @@ "$ref": "#/components/schemas/A2AAgentIDRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -22322,7 +22291,7 @@ "post": { "operationId": "session-read-list", "summary": "List sessions", - "description": "List agent sessions visible to the caller within the resolved account, filtered by app, entry surface, archive status, and team scope, with pagination. Reads are scoped to the person the app_key resolves to.", + "description": "List agent sessions visible to the caller, filtered by app, surface, archive status, and team.", "tags": [ "AI SRE/Sessions" ], @@ -22332,28 +22301,12 @@ } ], "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", + "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- Pagination uses `p`/`limit` (max 100); `scope` defaults to `all` (own + member-of-team rows).\n- `is_running` reflects the live run-set; `has_unread` is computed per calling user.\n", "href": "/en/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "List sessions" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionListRequest" - }, - "example": { - "app_name": "ai-sre", - "limit": 2, - "orderby": "updated_at", - "scope": "all" - } - } - } - }, "responses": { "200": { "description": "Success", @@ -22424,6 +22377,22 @@ "500": { "$ref": "#/components/responses/ServerError" } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionListRequest" + }, + "example": { + "app_name": "ai-sre", + "limit": 2, + "orderby": "updated_at", + "scope": "all" + } + } + } } } }, @@ -22431,7 +22400,7 @@ "post": { "operationId": "session-read-info", "summary": "Get session detail", - "description": "Fetch one session plus a backward-paged window of its most recent events. Use search_after_ctx to page through older history.", + "description": "Fetch one session plus a backward-paged window of its most recent events.", "tags": [ "AI SRE/Sessions" ], @@ -22441,26 +22410,12 @@ } ], "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", + "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- Page older history with `search_after_ctx` from the previous response.\n- `limit` (or legacy `num_recent_events`) caps the event page; default 100, max 1000.\n", "href": "/en/api-reference/ai-sre/sessions/session-read-info", "metadata": { "sidebarTitle": "Get session detail" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionGetRequest" - }, - "example": { - "session_id": "sess_f8oDvqiG64uur6sBNsTc4u", - "num_recent_events": 50 - } - } - } - }, "responses": { "200": { "description": "Success", @@ -22551,15 +22506,26 @@ "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/SessionGetRequest" + }, + "example": { + "session_id": "sess_f8oDvqiG64uur6sBNsTc4u", + "num_recent_events": 50 + } + } + } } } }, @@ -22567,7 +22533,7 @@ "post": { "operationId": "session-read-export", "summary": "Export session transcript", - "description": "Stream a session's full event transcript as NDJSON (application/x-ndjson), one JSON object per line. The first line is always a session_meta envelope; subsequent lines are session events (see the ExportLine schema). Parse the body line-by-line and write to a file — do NOT buffer the entire transcript into memory. When include_subagents is true, each subagent_dispatch line is followed by the child session's own stream.", + "description": "Stream a session's full event transcript as newline-delimited JSON.", "tags": [ "AI SRE/Sessions" ], @@ -22577,12 +22543,37 @@ } ], "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", + "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- The response is `application/x-ndjson` — parse line-by-line and write to a file; do not buffer the whole body in memory.\n- The first line is always a `session_meta` envelope; `include_subagents=true` inlines each child session's stream after its dispatch line.\n", "href": "/en/api-reference/ai-sre/sessions/session-read-export", "metadata": { "sidebarTitle": "Export session transcript" } }, + "responses": { + "200": { + "description": "Streaming NDJSON (application/x-ndjson). One JSON object per line, terminated by a newline. The first line is always a `session_meta` envelope; subsequent lines are session events.", + "content": { + "application/x-ndjson": { + "schema": { + "type": "string", + "description": "Newline-delimited JSON stream. Parse line-by-line; do not buffer the whole body." + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, "requestBody": { "required": true, "content": { @@ -22596,17 +22587,54 @@ } } } + } + } + }, + "/safari/session/delete": { + "post": { + "operationId": "session-write-delete", + "summary": "Delete session", + "description": "Delete a session by ID.", + "tags": [ + "AI SRE/Sessions" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "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- Requires manage rights on the session (creator, account admin, or owning-team member).\n", + "href": "/en/api-reference/ai-sre/sessions/session-write-delete", + "metadata": { + "sidebarTitle": "Delete session" + } }, "responses": { "200": { - "description": "Streaming NDJSON (application/x-ndjson). One JSON object per line, terminated by a newline. The first line is always a `session_meta` envelope; subsequent lines are session events (see ExportLine).", + "description": "Success", "content": { - "application/x-ndjson": { + "application/json": { "schema": { - "type": "string", - "description": "Newline-delimited JSON stream. Parse line-by-line; do not buffer the whole body. Each line decodes to an ExportLine object — see #/components/schemas/ExportLine." + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "null", + "description": "Always null on success." + } + } + } + ] }, - "example": "{\"type\":\"session_meta\",\"session_id\":\"sess_f8oDvqiG64uur6sBNsTc4u\",\"account_id\":2451002751131,\"app_name\":\"ai-sre\",\"started_at\":\"2026-06-02T02:39:31.228Z\",\"ended_at\":\"2026-06-02T02:39:53.457Z\",\"model\":\"deepseek-v4-pro\"}\n{\"type\":\"user_message\",\"seq\":1,\"ts\":\"2026-06-02T02:39:31.241Z\"}\n{\"type\":\"user_message\",\"seq\":2,\"ts\":\"2026-06-02T02:39:31.245Z\",\"content\":\" ... \"}\n{\"type\":\"final_answer\",\"seq\":3,\"ts\":\"2026-06-02T02:39:53.457Z\",\"content\":\"## Conclusion: noise alert, not a real incident ...\"}\n" + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null + } } } }, @@ -22616,15 +22644,25 @@ "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/SessionDeleteRequest" + }, + "example": { + "session_id": "sess_f8oDvqiG64uur6sBNsTc4u" + } + } + } } } } @@ -22648,11 +22686,12 @@ }, "examples": { "missingParameter": { + "summary": "Missing required parameter", "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "InvalidParameter", - "message": "The specified parameter is not valid." + "message": "The specified parameter skill_id is not valid." } } } @@ -22689,7 +22728,7 @@ "$ref": "#/components/schemas/ErrorResponse" }, "examples": { - "noEditPermission": { + "accessDenied": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { @@ -22724,7 +22763,7 @@ } }, "TooManyRequests": { - "description": "Rate limit hit. Either the global API limit, a per-account limit, or a per-integration limit.", + "description": "Rate limit hit. Either the global API limit or a per-account limit.", "content": { "application/json": { "schema": { @@ -22769,7 +22808,7 @@ "schemas": { "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. |", + "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational.", "enum": [ "OK", "InvalidParameter", @@ -22791,30 +22830,7 @@ "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" + ] }, "DutyError": { "type": "object", @@ -22825,8 +22841,7 @@ }, "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." + "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request." } }, "required": [ @@ -39177,11 +39192,11 @@ }, "MCPServerStatusRequest": { "type": "object", - "description": "Selector for the server whose status is being changed.", + "description": "MCP server enable/disable by ID.", "properties": { "server_id": { "type": "string", - "description": "Identifier of the target server." + "description": "Target MCP server ID." } }, "required": [ @@ -39190,114 +39205,114 @@ }, "SkillItem": { "type": "object", - "description": "An AI SRE skill — a packaged capability the agent can load at runtime.", + "description": "An AI SRE skill — a packaged SKILL.md bundle the agent can load.", "properties": { "skill_id": { "type": "string", - "description": "Unique identifier of the skill." + "description": "Unique skill ID (prefix `skill_`)." }, "account_id": { "type": "integer", - "format": "int64", - "description": "Owning account." + "description": "Owning account ID.", + "format": "int64" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team; 0 means account scope." + "description": "Team scope: 0 = account-wide; >0 = the owning team.", + "format": "int64" }, "skill_name": { "type": "string", - "description": "Name of the skill, parsed from its SKILL.md frontmatter." + "description": "Skill name, unique within the account." }, "description": { "type": "string", - "description": "What the skill does and when the agent should use it." + "description": "Human-readable description from the SKILL.md frontmatter." }, "content": { "type": "string", - "description": "Full SKILL.md body; omitted in list responses." + "description": "Full SKILL.md content. Omitted in list responses." }, "version": { "type": "string", - "description": "Skill version string from its frontmatter." + "description": "Skill version from the frontmatter." }, "tags": { "type": "array", "items": { "type": "string" }, - "description": "Tags declared in the skill frontmatter." + "description": "Tags parsed from the frontmatter." }, "author": { "type": "string", - "description": "Author declared in the skill frontmatter." + "description": "Skill author." }, "license": { "type": "string", - "description": "License declared in the skill frontmatter." + "description": "Skill license." }, "tools": { "type": "array", "items": { "type": "string" }, - "description": "Tools the skill requires, declared in its frontmatter." + "description": "Required tools (builtin or `mcp:server/tool`)." }, "s3_key": { "type": "string", - "description": "Object-storage key of the skill's zip package." + "description": "Object-storage key of the skill zip." }, "checksum": { "type": "string", - "description": "SHA-256 checksum of the skill's zip package." + "description": "SHA-256 checksum of the skill zip." }, "status": { "type": "string", + "description": "Skill status.", "enum": [ "enabled", "disabled" - ], - "description": "Whether the skill is active and loadable by agents." + ] }, "created_by": { "type": "integer", - "format": "int64", - "description": "Member who created this resource." + "description": "Member ID that created the skill.", + "format": "int64" }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation time as a Unix timestamp in milliseconds." + "description": "Creation time. Unix timestamp in milliseconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last-update time as a Unix timestamp in milliseconds." + "description": "Last update time. Unix timestamp in milliseconds." }, "can_edit": { "type": "boolean", - "description": "Whether the calling member may edit or delete this resource." + "description": "Whether the caller may edit this skill." }, "source_template_name": { "type": "string", - "description": "Marketplace template this skill was installed from, if any." + "description": "Marketplace template this skill was installed from; empty for user-authored." }, "source_template_version": { "type": "string", - "description": "Marketplace template version captured at install time." + "description": "Template version at install time." }, "update_available": { "type": "boolean", - "description": "A newer marketplace template version exists for this skill." + "description": "True when the marketplace has a newer template version." }, "is_modified": { "type": "boolean", - "description": "A marketplace-sourced skill has been edited locally; auto-update skips it." + "description": "True when a marketplace-sourced skill was edited locally (auto-update skips it)." }, "created": { "type": "boolean", - "description": "Install response only: true for a fresh install, false for an in-place upsert." + "description": "Set only on install-from-session responses: true = fresh install, false = in-place update." } }, "required": [ @@ -39501,15 +39516,17 @@ }, "A2AAgentListRequest": { "type": "object", - "description": "Filters for listing A2A agents.", + "description": "Pagination and team filter for listing A2A agents.", "properties": { "offset": { "type": "integer", - "description": "Number of rows to skip for pagination." + "description": "Row offset for pagination.", + "default": 0 }, "limit": { "type": "integer", - "description": "Maximum number of rows to return; defaults to 20." + "description": "Page size.", + "default": 20 }, "team_ids": { "type": "array", @@ -39517,31 +39534,37 @@ "type": "integer", "format": "int64" }, - "description": "Restrict results to resources owned by these teams; intersected with the caller's visible set." + "description": "Filter to these team IDs; empty = the caller's visible set." }, "include_account": { - "type": "boolean", - "description": "Include account-scoped rows alongside team-scoped ones; defaults to true." + "type": [ + "boolean", + "null" + ], + "description": "Include account-scoped (team_id=0) rows. Defaults to true." } } }, "SkillUpdateRequest": { "type": "object", - "description": "Editable fields of a skill.", + "description": "Editable skill metadata.", "properties": { "skill_id": { "type": "string", - "description": "Identifier of the skill to update." + "description": "Target skill ID." }, "description": { "type": "string", - "maxLength": 1024, - "description": "New description for the skill." + "description": "New description.", + "maxLength": 1024 }, "team_id": { - "type": "integer", - "format": "int64", - "description": "Reassign the skill to this team; omit to leave unchanged, 0 for account scope." + "type": [ + "integer", + "null" + ], + "description": "Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged.", + "format": "int64" } }, "required": [ @@ -39554,15 +39577,15 @@ "properties": { "total": { "type": "integer", - "format": "int64", - "description": "Total number of servers matching the filters." + "description": "Total number of matching servers.", + "format": "int64" }, "servers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerItem" }, - "description": "MCP servers on the current page." + "description": "MCP servers on this page." } }, "required": [ @@ -39572,75 +39595,75 @@ }, "MCPServerItem": { "type": "object", - "description": "A configured MCP (Model Context Protocol) server the agent can call tools through.", + "description": "An MCP server (connector) registered on the account.", "properties": { "server_id": { "type": "string", - "description": "Unique identifier of the MCP server." + "description": "Unique MCP server ID (prefix `mcp_`)." }, "account_id": { "type": "integer", - "format": "int64", - "description": "Owning account." + "description": "Owning account ID.", + "format": "int64" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team; 0 means account scope." + "description": "Team scope: 0 = account-wide; >0 = the owning team.", + "format": "int64" }, "can_edit": { "type": "boolean", - "description": "Whether the calling member may edit or delete this resource." + "description": "Whether the caller may edit this server." }, "server_name": { "type": "string", - "description": "Display name of the MCP server." + "description": "MCP server name, unique within the account." }, "description": { "type": "string", - "description": "What this MCP server provides." + "description": "Server description." }, "ai_description": { "type": "string", - "description": "LLM-generated description, preferred over description when present." + "description": "LLM-generated description, preferred over `description` when present." }, "transport": { "type": "string", + "description": "Transport protocol.", "enum": [ "stdio", "sse", "streamable-http" - ], - "description": "Transport used to reach the server." + ] }, "command": { "type": "string", - "description": "Executable launched for stdio transport." + "description": "Executable command (stdio transport only)." }, "args": { "type": "array", "items": { "type": "string" }, - "description": "Command-line arguments for the stdio executable." + "description": "Command arguments (stdio transport)." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Environment variables passed to the stdio process." + "description": "Environment variables (stdio transport). Secret values are masked." }, "url": { "type": "string", - "description": "Endpoint URL for sse or streamable-http transport." + "description": "Server URL (sse / streamable-http transport)." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "HTTP headers sent to the remote endpoint; secret values are masked." + "description": "HTTP headers (sse / streamable-http). Secret values are masked." }, "proxy_url": { "type": "string", @@ -39648,61 +39671,70 @@ }, "status": { "type": "string", + "description": "Server status.", "enum": [ "enabled", "disabled" - ], - "description": "Whether the server is active and usable by agents." + ] }, "connect_timeout": { "type": "integer", - "description": "Connection timeout in seconds." + "description": "Connection timeout in seconds (0 = server default, 10s)." }, "call_timeout": { "type": "integer", - "description": "Per-call timeout in seconds." + "description": "Tool-call timeout in seconds (0 = server default, 60s)." }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/MCPToolInfo" }, - "description": "Live tool catalogue; populated only by get and test." + "description": "Live tool list; populated by the get/test endpoints." }, "tool_count": { "type": "integer", - "description": "Number of tools discovered on the server." + "description": "Number of tools in the live list." }, "list_error": { "type": "string", - "description": "Tool-probe failure message; present when the live probe failed." + "description": "Error message when the live tool list failed." }, "auth_mode": { "type": "string", - "description": "Credential model: shared, per_user_secret, or per_user_oauth." + "description": "Authentication mode.", + "enum": [ + "shared", + "per_user_secret", + "per_user_oauth" + ] }, "secret_schema": { "type": "string", - "description": "JSON schema of the per-user secret." + "description": "JSON-encoded secret schema (per_user_secret mode)." }, "oauth_metadata": { "type": "string", - "description": "OAuth metadata JSON." + "description": "JSON-encoded OAuth metadata (per_user_oauth mode)." + }, + "source_template_name": { + "type": "string", + "description": "Marketplace template this connector was installed from; empty for user-authored." }, "created_by": { "type": "integer", - "format": "int64", - "description": "Member who created this resource." + "description": "Member ID that created the server.", + "format": "int64" }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation time as a Unix timestamp in milliseconds." + "description": "Creation time. Unix timestamp in milliseconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last-update time as a Unix timestamp in milliseconds." + "description": "Last update time. Unix timestamp in milliseconds." } }, "required": [ @@ -39723,18 +39755,20 @@ }, "MCPToolInfo": { "type": "object", - "description": "Metadata for a single tool exposed by an MCP server.", + "description": "Metadata for one tool exposed by an MCP server.", "properties": { "name": { "type": "string", - "description": "Tool name as advertised by the server." + "description": "Tool name." }, "description": { "type": "string", - "description": "What the tool does." + "description": "Tool description." }, "input_schema": { - "description": "JSON schema of the tool's input arguments." + "type": "object", + "additionalProperties": true, + "description": "JSON Schema describing the tool's input parameters." } }, "required": [ @@ -39742,19 +39776,6 @@ "description" ] }, - "SkillDownloadRequest": { - "type": "object", - "description": "Selector for the skill to download.", - "properties": { - "skill_id": { - "type": "string", - "description": "Identifier of the skill to download." - } - }, - "required": [ - "skill_id" - ] - }, "GetWarRoomDefaultObserversResponse": { "type": "object", "properties": { @@ -39828,11 +39849,11 @@ }, "SkillDeleteRequest": { "type": "object", - "description": "Selector for the skill to delete.", + "description": "Skill deletion by ID.", "properties": { "skill_id": { "type": "string", - "description": "Identifier of the skill to delete." + "description": "Target skill ID." } }, "required": [ @@ -39841,11 +39862,11 @@ }, "MCPServerGetRequest": { "type": "object", - "description": "Selector for a single MCP server.", + "description": "MCP server lookup by ID.", "properties": { "server_id": { "type": "string", - "description": "Identifier of the server to fetch." + "description": "Target MCP server ID." } }, "required": [ @@ -39871,11 +39892,11 @@ }, "SkillGetRequest": { "type": "object", - "description": "Selector for a single skill.", + "description": "Skill lookup by ID.", "properties": { "skill_id": { "type": "string", - "description": "Identifier of the skill to fetch." + "description": "Target skill ID." } }, "required": [ @@ -39888,15 +39909,15 @@ "properties": { "total": { "type": "integer", - "format": "int64", - "description": "Total number of skills matching the filters." + "description": "Total number of matching skills.", + "format": "int64" }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/SkillItem" }, - "description": "Skills on the current page." + "description": "Skills on this page." } }, "required": [ @@ -39993,11 +40014,11 @@ }, "SkillStatusRequest": { "type": "object", - "description": "Selector for the skill whose status is being changed.", + "description": "Skill enable/disable by ID.", "properties": { "skill_id": { "type": "string", - "description": "Identifier of the target skill." + "description": "Target skill ID." } }, "required": [ @@ -40010,86 +40031,91 @@ "properties": { "server_name": { "type": "string", + "description": "MCP server name, unique within the account.", "minLength": 1, - "maxLength": 255, - "description": "Display name of the server." + "maxLength": 255 }, "description": { "type": "string", + "description": "Server description.", "minLength": 1, - "maxLength": 1024, - "description": "What this MCP server provides." + "maxLength": 1024 }, "transport": { "type": "string", + "description": "Transport protocol.", "enum": [ "stdio", "sse", "streamable-http" - ], - "description": "Transport used to reach the server." + ] }, "command": { "type": "string", - "description": "Executable to launch for stdio transport." + "description": "Executable command (stdio transport)." }, "args": { "type": "array", "items": { "type": "string" }, - "description": "Command-line arguments for the stdio executable." + "description": "Command arguments (stdio transport)." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Environment variables for the stdio process." + "description": "Environment variables (stdio transport)." }, "url": { "type": "string", - "description": "Endpoint URL for sse or streamable-http transport." + "description": "Server URL (sse / streamable-http transport)." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "HTTP headers sent to the remote endpoint." + "description": "HTTP headers (sse / streamable-http)." }, "connect_timeout": { "type": "integer", - "description": "Connection timeout in seconds." + "description": "Connection timeout in seconds. 0 = default (10s)." }, "call_timeout": { "type": "integer", - "description": "Per-call timeout in seconds." + "description": "Tool-call timeout in seconds. 0 = default (60s)." + }, + "auth_mode": { + "type": "string", + "description": "Authentication mode: shared (default), per_user_secret, or per_user_oauth." + }, + "secret_schema": { + "type": "string", + "description": "JSON secret schema; required when auth_mode=per_user_secret." + }, + "oauth_metadata": { + "type": "string", + "description": "JSON OAuth metadata; reserved for per_user_oauth." }, "status": { "type": "string", + "description": "Initial status.", "enum": [ "enabled", "disabled" ], - "description": "Initial lifecycle state of the server." + "default": "enabled" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team for the new server; 0 for account scope." - }, - "auth_mode": { - "type": "string", - "description": "Credential model; defaults to shared." - }, - "secret_schema": { - "type": "string", - "description": "JSON schema of the per-user secret; required when auth_mode is per_user_secret." + "description": "Team scope: 0 = account-wide; >0 = team.", + "format": "int64" }, - "oauth_metadata": { + "source_template_name": { "type": "string", - "description": "OAuth metadata JSON; reserved for OAuth-based auth." + "description": "Marketplace template name when created from a connector template." } }, "required": [ @@ -40100,11 +40126,11 @@ }, "MCPServerDeleteRequest": { "type": "object", - "description": "Selector for the server to delete.", + "description": "MCP server deletion by ID.", "properties": { "server_id": { "type": "string", - "description": "Identifier of the server to delete." + "description": "Target MCP server ID." } }, "required": [ @@ -40113,15 +40139,17 @@ }, "SkillListRequest": { "type": "object", - "description": "Filters for listing skills.", + "description": "Pagination and team filter for listing skills.", "properties": { "p": { "type": "integer", - "description": "Page number, starting at 1." + "description": "Page number, 1-based.", + "default": 1 }, "limit": { "type": "integer", - "description": "Page size; defaults to 20." + "description": "Page size.", + "default": 20 }, "team_ids": { "type": "array", @@ -40129,96 +40157,102 @@ "type": "integer", "format": "int64" }, - "description": "Restrict results to resources owned by these teams; intersected with the caller's visible set." + "description": "Filter to these team IDs; empty = the caller's visible set." }, "include_account": { - "type": "boolean", - "description": "Include account-scoped rows alongside team-scoped ones; defaults to true." + "type": [ + "boolean", + "null" + ], + "description": "Include account-scoped (team_id=0) rows. Defaults to true." } } }, "MCPServerUpdateRequest": { "type": "object", - "description": "Editable fields of an MCP server; omitted fields are left unchanged.", + "description": "Partial update of an MCP server. Omit a field to leave it unchanged.", "properties": { "server_id": { "type": "string", - "description": "Identifier of the server to update." + "description": "Target MCP server ID." }, "server_name": { "type": "string", + "description": "New name.", "minLength": 1, - "maxLength": 255, - "description": "New display name." + "maxLength": 255 }, "description": { "type": "string", + "description": "New description.", "minLength": 1, - "maxLength": 1024, - "description": "New description." + "maxLength": 1024 }, "transport": { "type": "string", + "description": "Transport protocol.", "enum": [ "stdio", "sse", "streamable-http" - ], - "description": "New transport for the server." + ] }, "command": { "type": "string", - "description": "New stdio executable." + "description": "Executable command (stdio transport)." }, "args": { "type": "array", "items": { "type": "string" }, - "description": "New stdio arguments." + "description": "Command arguments (stdio transport)." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "New stdio environment variables." + "description": "Environment variables (stdio transport)." }, "url": { "type": "string", - "description": "New endpoint URL for remote transports." + "description": "Server URL (sse / streamable-http transport)." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "New HTTP headers for the remote endpoint." + "description": "HTTP headers (sse / streamable-http)." }, "connect_timeout": { "type": "integer", - "description": "New connection timeout in seconds." + "description": "Connection timeout in seconds. 0 = default (10s)." }, "call_timeout": { "type": "integer", - "description": "New per-call timeout in seconds." - }, - "team_id": { - "type": "integer", - "format": "int64", - "description": "Reassign the server to this team; omit to leave unchanged, 0 for account scope." + "description": "Tool-call timeout in seconds. 0 = default (60s)." }, "auth_mode": { "type": "string", - "description": "New credential model." + "description": "Authentication mode: shared (default), per_user_secret, or per_user_oauth." }, "secret_schema": { "type": "string", - "description": "New per-user secret JSON schema." + "description": "JSON secret schema; required when auth_mode=per_user_secret." }, "oauth_metadata": { "type": "string", - "description": "New OAuth metadata JSON." + "description": "JSON OAuth metadata; reserved for per_user_oauth." + }, + "team_id": { + "type": [ + "integer", + "null" + ], + "description": "Reassign team scope: 0 = account-wide; >0 = team. Omit to leave unchanged.", + "format": "int64" } }, "required": [ @@ -40347,12 +40381,12 @@ "items": { "$ref": "#/components/schemas/A2AAgentItem" }, - "description": "A2A agents on the current page." + "description": "A2A agents on this page." }, "total": { "type": "integer", - "format": "int64", - "description": "Total number of agents matching the filters." + "description": "Total number of matching agents.", + "format": "int64" } }, "required": [ @@ -40362,106 +40396,111 @@ }, "A2AAgentItem": { "type": "object", - "description": "A registered A2A (agent-to-agent) remote agent the SRE agent can delegate to.", + "description": "A registered A2A (agent-to-agent) remote agent.", "properties": { "agent_id": { "type": "string", - "description": "Unique identifier of the A2A agent." + "description": "Unique A2A agent ID (prefix `a2a_`)." }, "account_id": { "type": "integer", - "format": "int64", - "description": "Owning account." + "description": "Owning account ID.", + "format": "int64" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team; 0 means account scope." + "description": "Team scope: 0 = account-wide; >0 = the owning team.", + "format": "int64" }, "can_edit": { "type": "boolean", - "description": "Whether the calling member may edit or delete this resource." + "description": "Whether the caller may edit this agent." }, "agent_name": { "type": "string", - "description": "Display name of the agent." + "description": "Agent display name." }, "description": { "type": "string", - "description": "What this agent does and when to delegate to it." + "description": "Agent description." }, "card_url": { "type": "string", - "description": "URL of the agent's published A2A agent card." + "description": "URL of the remote agent card." }, "auth_type": { "type": "string", - "description": "Authentication scheme used when calling the agent." + "description": "Authentication type for reaching the remote agent." }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Authentication parameters keyed by name." + "description": "Authentication config; secret values are masked." }, "streaming": { "type": "boolean", - "description": "Whether the agent supports streaming responses." + "description": "Whether the remote agent supports streaming responses." }, "status": { "type": "string", + "description": "Agent status.", "enum": [ "enabled", "disabled" - ], - "description": "Whether the agent is active and reachable." + ] }, "agent_card_name": { "type": "string", - "description": "Name resolved from the fetched agent card." + "description": "Agent name resolved from the remote card." }, "agent_card_skills": { "type": "array", "items": { "type": "string" }, - "description": "Skills advertised on the fetched agent card." + "description": "Skills advertised by the remote card." }, "card_resolve_timeout": { "type": "integer", - "description": "Timeout for fetching the agent card, in seconds." + "description": "Card-resolution timeout in seconds." }, "task_timeout": { "type": "integer", - "description": "Timeout for a single delegated task, in seconds." + "description": "Single-task execution timeout in seconds." }, "auth_mode": { "type": "string", - "description": "Credential model: shared, per_user_secret, or per_user_oauth." + "description": "Authentication mode.", + "enum": [ + "shared", + "per_user_secret", + "per_user_oauth" + ] }, "secret_schema": { "type": "string", - "description": "JSON schema of the per-user secret." + "description": "JSON-encoded secret schema (per_user_secret mode)." }, "oauth_metadata": { "type": "string", - "description": "OAuth metadata JSON." + "description": "JSON-encoded OAuth metadata (per_user_oauth mode)." }, "created_by": { "type": "integer", - "format": "int64", - "description": "Member who created this resource." + "description": "Member ID that created the agent.", + "format": "int64" }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation time as a Unix timestamp in seconds." + "description": "Creation time. Unix timestamp in milliseconds." }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last-update time as a Unix timestamp in seconds." + "description": "Last update time. Unix timestamp in milliseconds." } }, "required": [ @@ -40484,56 +40523,83 @@ }, "A2AAgentUpdateRequest": { "type": "object", - "description": "Editable fields of an A2A agent; omitted fields are left unchanged.", + "description": "Partial update of an A2A agent. A null/omitted field is left unchanged.", "properties": { "agent_id": { "type": "string", - "description": "Identifier of the agent to update." + "description": "Target agent ID." }, "agent_name": { - "type": "string", - "maxLength": 128, - "description": "New display name." + "type": [ + "string", + "null" + ], + "description": "New display name. Omit to leave unchanged.", + "maxLength": 128 }, "description": { - "type": "string", - "description": "New description." + "type": [ + "string", + "null" + ], + "description": "New description. Omit to leave unchanged." }, "card_url": { - "type": "string", - "description": "New agent card URL." + "type": [ + "string", + "null" + ], + "description": "New card URL. Omit to leave unchanged." }, "auth_type": { - "type": "string", - "description": "New authentication scheme." + "type": [ + "string", + "null" + ], + "description": "New auth type. Omit to leave unchanged." }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "New authentication parameters." + "description": "Replace the auth config. Omit to leave unchanged." }, "streaming": { - "type": "boolean", - "description": "Toggle streaming-response support." + "type": [ + "boolean", + "null" + ], + "description": "Toggle streaming support. Omit to leave unchanged." }, "team_id": { - "type": "integer", - "format": "int64", - "description": "Reassign the agent to this team; omit to leave unchanged, 0 for account scope." + "type": [ + "integer", + "null" + ], + "description": "Reassign team scope. Omit to leave unchanged.", + "format": "int64" }, "auth_mode": { - "type": "string", - "description": "New credential model." + "type": [ + "string", + "null" + ], + "description": "New auth mode: shared, per_user_secret, or per_user_oauth." }, "secret_schema": { - "type": "string", - "description": "New per-user secret JSON schema." + "type": [ + "string", + "null" + ], + "description": "New JSON secret schema." }, "oauth_metadata": { - "type": "string", - "description": "New OAuth metadata JSON." + "type": [ + "string", + "null" + ], + "description": "New JSON OAuth metadata." } }, "required": [ @@ -40542,52 +40608,52 @@ }, "A2AAgentCreateRequest": { "type": "object", - "description": "Configuration for a new A2A agent.", + "description": "Registration parameters for a new A2A agent.", "properties": { "agent_name": { "type": "string", - "maxLength": 128, - "description": "Display name of the agent." + "description": "Agent display name.", + "maxLength": 128 }, "description": { "type": "string", - "description": "What this agent does and when to delegate to it." + "description": "Agent description." }, "card_url": { "type": "string", - "description": "URL of the agent's published A2A agent card." + "description": "URL of the remote agent card." }, "auth_type": { "type": "string", - "description": "Authentication scheme used when calling the agent." + "description": "Authentication type for the remote agent." }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Authentication parameters keyed by name." + "description": "Authentication config key-values." }, "streaming": { "type": "boolean", - "description": "Whether the agent supports streaming responses." + "description": "Whether the remote agent supports streaming." }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team for the new agent; 0 for account scope." + "description": "Team scope: 0 = account-wide; >0 = team.", + "format": "int64" }, "auth_mode": { "type": "string", - "description": "Credential model; defaults to shared." + "description": "Authentication mode: shared (default), per_user_secret, or per_user_oauth." }, "secret_schema": { "type": "string", - "description": "JSON schema of the per-user secret; required when auth_mode is per_user_secret." + "description": "JSON secret schema; required when auth_mode=per_user_secret." }, "oauth_metadata": { "type": "string", - "description": "OAuth metadata JSON; reserved for OAuth-based auth." + "description": "JSON OAuth metadata; reserved for per_user_oauth." } }, "required": [ @@ -40597,15 +40663,17 @@ }, "MCPServerListRequest": { "type": "object", - "description": "Filters for listing MCP servers.", + "description": "Pagination and team filter for listing MCP servers.", "properties": { "p": { "type": "integer", - "description": "Page number, starting at 1." + "description": "Page number, 1-based.", + "default": 1 }, "limit": { "type": "integer", - "description": "Page size; defaults to 20." + "description": "Page size.", + "default": 20 }, "team_ids": { "type": "array", @@ -40613,21 +40681,24 @@ "type": "integer", "format": "int64" }, - "description": "Restrict results to resources owned by these teams; intersected with the caller's visible set." + "description": "Filter to these team IDs; empty = the caller's visible set." }, "include_account": { - "type": "boolean", - "description": "Include account-scoped rows alongside team-scoped ones; defaults to true." + "type": [ + "boolean", + "null" + ], + "description": "Include account-scoped (team_id=0) rows. Defaults to true." } } }, "A2AAgentCreateResponse": { "type": "object", - "description": "Identifier of the newly created A2A agent.", + "description": "Result of registering an A2A agent.", "properties": { "agent_id": { "type": "string", - "description": "Identifier of the created agent." + "description": "ID of the newly created agent." } }, "required": [ @@ -40770,11 +40841,11 @@ }, "A2AAgentIDRequest": { "type": "object", - "description": "Selector for a single A2A agent.", + "description": "A2A agent lookup by ID.", "properties": { "agent_id": { "type": "string", - "description": "Identifier of the target agent." + "description": "Target agent ID." } }, "required": [ @@ -40944,7 +41015,7 @@ }, "SessionListRequest": { "type": "object", - "description": "Filters for listing agent sessions. Reads are scoped to the account the app_key resolves to and to the resolved person's visible teams.", + "description": "Filters for listing agent sessions. Reads are scoped to the resolved account and the caller's visible teams.", "properties": { "app_name": { "type": "string", @@ -40955,22 +41026,26 @@ "support-website", "support-flashcat", "ai-sre", - "template-assistant" + "template-assistant", + "swe" ] }, "p": { "type": "integer", - "description": "1-based page number; defaults to 1." + "description": "Page number, 1-based.", + "default": 1, + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size, 1..100; defaults to 20.", + "description": "Page size, 1–100.", "minimum": 1, - "maximum": 100 + "maximum": 100, + "default": 20 }, "orderby": { "type": "string", - "description": "Sort column.", + "description": "Sort field.", "enum": [ "created_at", "updated_at" @@ -40978,20 +41053,20 @@ }, "asc": { "type": "boolean", - "description": "Ascending sort when true; defaults to false (descending). Only honored when orderby is set." + "description": "Ascending order when true; applies only when `orderby` is set." }, "include_subagent_sessions": { "type": "boolean", - "description": "Include subagent (child) sessions in the result; defaults to false." + "description": "Include subagent-dispatched sessions in the list." }, "keyword": { "type": "string", - "maxLength": 64, - "description": "Case-insensitive substring match against session name." + "description": "Filter by session-name keyword.", + "maxLength": 64 }, "scope": { "type": "string", - "description": "Visibility scope: all (own + member-of-team rows, the default), personal (own only), or team (member teams only).", + "description": "Visibility scope: all (own + member-of-team rows, default), personal, or team.", "enum": [ "all", "personal", @@ -41004,7 +41079,7 @@ "type": "integer", "format": "int64" }, - "description": "Optional explicit team filter; intersected with the caller's visible set / scope." + "description": "Optional explicit team filter; intersects with `scope`." }, "entry_kinds": { "type": "array", @@ -41014,14 +41089,14 @@ "web", "im", "api", - "scheduled" + "automation" ] }, - "description": "Restrict to sessions produced by these entry surfaces. Empty returns every kind." + "description": "Restrict to sessions produced by these surfaces; empty returns every kind." }, "status": { "type": "string", - "description": "Archive bucket: active (default, not archived), archived, or all.", + "description": "Archive bucket: active (default) returns un-archived, archived returns archived, all returns both.", "enum": [ "active", "archived", @@ -41258,29 +41333,29 @@ }, "SessionGetRequest": { "type": "object", - "description": "Fetch one session plus a recent page of its events.", + "description": "Fetch one session plus a backward-paged window of its most recent events.", "properties": { "session_id": { "type": "string", - "minLength": 1, - "description": "Session identifier." + "description": "Target session ID.", + "minLength": 1 }, "num_recent_events": { "type": "integer", + "description": "Legacy page size: number of most-recent events to return. Superseded by `limit` when both are set; 0 uses the server default (100).", "minimum": 0, - "maximum": 1000, - "description": "Number of most-recent events to return; 0 uses the server default." + "maximum": 1000 }, "limit": { "type": "integer", + "description": "Page size for events; takes precedence over `num_recent_events`. 0 uses the server default (100).", "minimum": 0, - "maximum": 1000, - "description": "Alias for num_recent_events; takes precedence when both are set." + "maximum": 1000 }, "search_after_ctx": { "type": "string", - "maxLength": 4096, - "description": "Opaque keyset cursor from a previous response's search_after_ctx, to page backward through older events." + "description": "Opaque keyset cursor from a previous response; pass it back to fetch the next older page.", + "maxLength": 4096 } }, "required": [ @@ -41387,7 +41462,7 @@ "properties": { "session_id": { "type": "string", - "description": "Session identifier to export." + "description": "Target session ID." }, "include_subagents": { "type": "boolean", @@ -41398,136 +41473,46 @@ "session_id" ] }, - "ExportUsage": { + "SkillUploadRequest": { "type": "object", - "description": "Per-LLM-call token counts on an export line. Absent fields are 0.", + "description": "Multipart form for uploading a skill archive.", "properties": { - "input_tokens": { - "type": "integer", - "description": "Prompt (input) tokens for the call." + "file": { + "type": "string", + "format": "binary", + "description": "Skill archive (.skill / .zip / .tar.gz / .tgz). Max 100MB." }, - "output_tokens": { + "team_id": { "type": "integer", - "description": "Generated (output) tokens for the call." + "description": "Team scope for the new skill: 0 = account-wide.", + "format": "int64" }, - "cache_read": { - "type": "integer", - "description": "Tokens served from the prompt cache." + "replace": { + "type": "boolean", + "description": "When true, overwrite an existing same-name skill." }, - "cache_creation": { - "type": "integer", - "description": "Tokens written to the prompt cache." + "skill_id": { + "type": "string", + "description": "When replacing a specific skill, its skill ID." } - } + }, + "required": [ + "file" + ] }, - "ExportLine": { + "SessionDeleteRequest": { "type": "object", - "description": "One line of the NDJSON export stream. The `type` field discriminates the line: session_meta (always first), user_message, llm_call, tool_call, subagent_dispatch, final_answer, agent_text, or error (emitted only if the stream is truncated mid-export). Fields are sparse — only those relevant to the line type are present.", + "description": "Session deletion by ID.", "properties": { - "type": { - "type": "string", - "description": "Line discriminator.", - "enum": [ - "session_meta", - "user_message", - "llm_call", - "tool_call", - "subagent_dispatch", - "final_answer", - "agent_text", - "error" - ] - }, - "seq": { - "type": "integer", - "description": "1-based monotonic sequence within the session (absent on session_meta)." - }, "session_id": { "type": "string", - "description": "Session id (on session_meta)." - }, - "account_id": { - "type": "integer", - "format": "int64", - "description": "Account id (on session_meta)." - }, - "app_name": { - "type": "string", - "description": "Agent app (on session_meta)." - }, - "parent_session_id": { - "type": "string", - "description": "Parent session id for child sessions (on session_meta)." - }, - "started_at": { - "type": "string", - "format": "date-time", - "description": "RFC3339 start timestamp (session_meta uses session.created_at)." - }, - "ended_at": { - "type": "string", - "format": "date-time", - "description": "RFC3339 end timestamp; stamped on llm_call/tool_call/session_meta." - }, - "model": { - "type": "string", - "description": "Chat model provider key; on session_meta and llm_call." - }, - "content": { - "type": "string", - "description": "Text content of the line (messages, answers, errors)." - }, - "ts": { - "type": "string", - "format": "date-time", - "description": "RFC3339 timestamp of the event." - }, - "usage": { - "$ref": "#/components/schemas/ExportUsage" - }, - "name": { - "type": "string", - "description": "Tool name (on tool_call)." - }, - "input": { - "type": "object", - "additionalProperties": true, - "description": "Tool call input arguments (on tool_call)." - }, - "output": { - "type": "string", - "description": "Tool call output (on tool_call response side)." - }, - "status": { - "type": "string", - "description": "Tool result status, e.g. ok or error." - }, - "duration_ms": { - "type": "integer", - "format": "int64", - "description": "Call duration in milliseconds." - }, - "input_bytes": { - "type": "integer", - "description": "Byte size of the tool input." - }, - "output_bytes": { - "type": "integer", - "description": "Byte size of the tool output." - }, - "error": { - "type": "string", - "description": "Error detail when a call failed." - }, - "agent_name": { - "type": "string", - "description": "Dispatched subagent name (on subagent_dispatch)." - }, - "child_session_id": { - "type": "string", - "description": "Child session id created by the dispatch (on subagent_dispatch)." + "description": "Target session ID.", + "minLength": 1 } - } + }, + "required": [ + "session_id" + ] } } } diff --git a/openapi/openapi.zh.json b/openapi/openapi.zh.json index cf2ce10..078a2e1 100644 --- a/openapi/openapi.zh.json +++ b/openapi/openapi.zh.json @@ -20382,7 +20382,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 列表行中省略 `content` 字段；如需读取技能正文，请查询单个技能详情。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 列表行中省略 `content` 字段；如需正文请单独查询某个技能。\n", "href": "/zh/api-reference/ai-sre/skills/skill-read-list", "metadata": { "sidebarTitle": "查询技能列表" @@ -20414,7 +20414,7 @@ "total": 1, "skills": [ { - "skill_id": "skl-7f3a9c21b8e0", + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", "account_id": 10023, "team_id": 0, "skill_name": "k8s-triage", @@ -20425,6 +20425,10 @@ "triage" ], "author": "sre-team", + "tools": [ + "bash", + "mcp:prometheus/query" + ], "status": "enabled", "created_by": 80011, "created_at": 1716960000000, @@ -20473,7 +20477,7 @@ "post": { "operationId": "skill-read-get", "summary": "查看技能详情", - "description": "按 ID 返回单个技能的完整配置及 SKILL.md 正文。", + "description": "查看单个技能，包含完整的 SKILL.md 内容。", "tags": [ "AI SRE/技能" ], @@ -20512,7 +20516,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "skill_id": "skl-7f3a9c21b8e0", + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", "account_id": 10023, "team_id": 0, "skill_name": "k8s-triage", @@ -20523,6 +20527,10 @@ "triage" ], "author": "sre-team", + "tools": [ + "bash", + "mcp:prometheus/query" + ], "status": "enabled", "created_by": 80011, "created_at": 1716960000000, @@ -20530,7 +20538,7 @@ "can_edit": true, "update_available": false, "is_modified": false, - "content": "---\nname: k8s-triage\n---\nDiagnose unhealthy workloads..." + "content": "---\nname: k8s-triage\ndescription: ...\n---\n# Triage steps" } } } @@ -20557,7 +20565,7 @@ "$ref": "#/components/schemas/SkillGetRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m" } } } @@ -20568,7 +20576,7 @@ "post": { "operationId": "skill-write-update", "summary": "更新技能", - "description": "编辑技能的描述或重新指定其所属团队。", + "description": "更新技能的描述或重新分配团队范围。", "tags": [ "AI SRE/技能" ], @@ -20578,7 +20586,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅可更新调用者有权编辑的技能，否则返回 AccessDenied。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅 `description` 与 `team_id` 可编辑；技能正文需通过重新上传修改。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/skills/skill-write-update", "metadata": { "sidebarTitle": "更新技能" @@ -20607,17 +20615,21 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "skill_id": "skl-7f3a9c21b8e0", + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", "account_id": 10023, "team_id": 0, "skill_name": "k8s-triage", - "description": "Diagnose unhealthy Kubernetes workloads.", + "description": "Updated triage runbook.", "version": "1.2.0", "tags": [ "kubernetes", "triage" ], "author": "sre-team", + "tools": [ + "bash", + "mcp:prometheus/query" + ], "status": "enabled", "created_by": 80011, "created_at": 1716960000000, @@ -20636,6 +20648,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -20651,8 +20666,8 @@ "$ref": "#/components/schemas/SkillUpdateRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0", - "description": "Diagnose unhealthy Kubernetes workloads." + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", + "description": "Updated triage runbook." } } } @@ -20663,7 +20678,7 @@ "post": { "operationId": "skill-write-delete", "summary": "删除技能", - "description": "永久删除技能，使智能体无法再加载它。", + "description": "按 ID 删除技能。", "tags": [ "AI SRE/技能" ], @@ -20673,7 +20688,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/skills/skill-write-delete", "metadata": { "sidebarTitle": "删除技能" @@ -20694,14 +20709,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -20712,6 +20728,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -20727,7 +20746,7 @@ "$ref": "#/components/schemas/SkillDeleteRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m" } } } @@ -20738,7 +20757,7 @@ "post": { "operationId": "skill-write-upload", "summary": "上传技能", - "description": "上传技能 zip 包并注册为新的账户或团队技能。", + "description": "上传技能压缩包（.skill/.zip/.tar.gz/.tgz）以创建或覆盖技能。", "tags": [ "AI SRE/技能" ], @@ -20748,7 +20767,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 请求体为 `multipart/form-data`，包含 `file` 部分（zip 包）与可选的 `team_id` 字段，而非 JSON。\n- 技能名称重复时返回 InvalidParameter。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **30 次/分钟**；**3 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 以 `multipart/form-data` 提交，包含 `file` 部分。压缩包最大 100MB。\n- 设置 `replace=true` 可覆盖同名技能。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/skills/skill-write-upload", "metadata": { "sidebarTitle": "上传技能" @@ -20777,7 +20796,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "skill_id": "skl-7f3a9c21b8e0", + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m", "account_id": 10023, "team_id": 0, "skill_name": "k8s-triage", @@ -20788,13 +20807,18 @@ "triage" ], "author": "sre-team", + "tools": [ + "bash", + "mcp:prometheus/query" + ], "status": "enabled", "created_by": 80011, "created_at": 1716960000000, "updated_at": 1717046400000, "can_edit": true, "update_available": false, - "is_modified": false + "is_modified": false, + "created": true } } } @@ -20806,93 +20830,8 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, - "429": { - "$ref": "#/components/responses/TooManyRequests" - }, - "500": { - "$ref": "#/components/responses/ServerError" - } - }, - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "type": "object", - "properties": { - "file": { - "type": "string", - "format": "binary", - "description": "Skill zip package to upload." - }, - "team_id": { - "type": "integer", - "format": "int64", - "description": "Owning team for the new skill; 0 for account scope." - } - }, - "required": [ - "file" - ] - } - } - } - } - } - }, - "/safari/skill/download": { - "post": { - "operationId": "skill-read-download", - "summary": "下载技能", - "description": "以二进制附件形式下载技能的原始 zip 包。", - "tags": [ - "AI SRE/技能" - ], - "security": [ - { - "AppKeyAuth": [] - } - ], - "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应为 `application/zip` 字节流并带有 `Content-Disposition` 附件头，而非 JSON 响应包。\n", - "href": "/zh/api-reference/ai-sre/skills/skill-read-download", - "metadata": { - "sidebarTitle": "下载技能" - } - }, - "responses": { - "200": { - "description": "Success", - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/ResponseEnvelope" - }, - { - "type": "object", - "properties": { - "data": { - "type": "string", - "format": "binary", - "description": "Raw zip bytes (not wrapped in the JSON envelope)." - } - } - } - ] - }, - "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" - } - } - } - }, - "400": { - "$ref": "#/components/responses/BadRequest" - }, - "401": { - "$ref": "#/components/responses/Unauthorized" + "403": { + "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" @@ -20904,12 +20843,13 @@ "requestBody": { "required": true, "content": { - "application/json": { + "multipart/form-data": { "schema": { - "$ref": "#/components/schemas/SkillDownloadRequest" + "$ref": "#/components/schemas/SkillUploadRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "team_id": 0, + "replace": false } } } @@ -20920,7 +20860,7 @@ "post": { "operationId": "skill-read-enable", "summary": "启用技能", - "description": "启用已禁用的技能，使智能体可在会话开始时加载它。", + "description": "启用已禁用的技能，使智能体可加载。", "tags": [ "AI SRE/技能" ], @@ -20930,7 +20870,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅可启用已禁用的技能；若技能已启用则返回 InvalidParameter。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅可启用 `disabled` 状态的技能，否则返回 InvalidParameter。\n", "href": "/zh/api-reference/ai-sre/skills/skill-read-enable", "metadata": { "sidebarTitle": "启用技能" @@ -20951,14 +20891,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -20969,6 +20910,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -20984,7 +20928,7 @@ "$ref": "#/components/schemas/SkillStatusRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m" } } } @@ -20995,7 +20939,7 @@ "post": { "operationId": "skill-write-disable", "summary": "禁用技能", - "description": "禁用已启用的技能，使智能体不再加载它。", + "description": "禁用已启用的技能，使智能体不再加载。", "tags": [ "AI SRE/技能" ], @@ -21005,7 +20949,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 仅可禁用已启用的技能；若技能已禁用则返回 InvalidParameter。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Skill 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 仅可禁用 `enabled` 状态的技能，否则返回 InvalidParameter。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/skills/skill-write-disable", "metadata": { "sidebarTitle": "禁用技能" @@ -21026,14 +20970,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -21044,6 +20989,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21059,7 +21007,7 @@ "$ref": "#/components/schemas/SkillStatusRequest" }, "example": { - "skill_id": "skl-7f3a9c21b8e0" + "skill_id": "skill_8s7Hn2kLpQ3xYbVc4Wd2m" } } } @@ -21080,7 +21028,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 列表不含实时工具列表；如需探测工具请单独查询某个服务器。\n", "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-read-server-list", "metadata": { "sidebarTitle": "查询 MCP 服务器列表" @@ -21112,25 +21060,28 @@ "total": 1, "servers": [ { - "server_id": "mcp-2b5e8d14a7c9", + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", "account_id": 10023, "team_id": 0, "can_edit": true, - "server_name": "GitHub Tools", - "description": "Read issues and pull requests from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, + "server_name": "prometheus", + "description": "Query Prometheus metrics and alerts.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", "status": "enabled", "connect_timeout": 10, - "call_timeout": 30, - "tool_count": 12, + "call_timeout": 60, + "tool_count": 2, + "tools": [ + { + "name": "query", + "description": "Run a PromQL instant query." + }, + { + "name": "query_range", + "description": "Run a PromQL range query." + } + ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -21176,7 +21127,7 @@ "post": { "operationId": "mcp-write-server-create", "summary": "创建 MCP 服务器", - "description": "注册一个新的 MCP 服务器，供智能体调用其工具。", + "description": "在账户下注册新的 MCP 服务器（连接器）。", "tags": [ "AI SRE/MCP 服务器" ], @@ -21186,7 +21137,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- `transport` 必须为 stdio、sse 或 streamable-http 之一，否则返回 InvalidParameter。\n- 服务器名称重复时返回 InvalidParameter。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `command`/`args`/`env` 用于 `stdio`；`url`/`headers` 用于 `sse`/`streamable-http`。\n- 服务器名称在账户内必须唯一，重复将返回 InvalidParameter。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-create", "metadata": { "sidebarTitle": "创建 MCP 服务器" @@ -21215,25 +21166,28 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "server_id": "mcp-2b5e8d14a7c9", + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", "account_id": 10023, "team_id": 0, "can_edit": true, - "server_name": "GitHub Tools", - "description": "Read issues and pull requests from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, + "server_name": "prometheus", + "description": "Query Prometheus metrics and alerts.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", "status": "enabled", "connect_timeout": 10, - "call_timeout": 30, - "tool_count": 12, + "call_timeout": 60, + "tool_count": 2, + "tools": [ + { + "name": "query", + "description": "Run a PromQL instant query." + }, + { + "name": "query_range", + "description": "Run a PromQL range query." + } + ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -21249,6 +21203,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21264,19 +21221,11 @@ "$ref": "#/components/schemas/MCPServerCreateRequest" }, "example": { - "server_name": "GitHub Tools", - "description": "Read issues and pull requests from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, - "status": "enabled", - "team_id": 0 + "server_name": "prometheus", + "description": "Query Prometheus metrics and alerts.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", + "status": "enabled" } } } @@ -21287,7 +21236,7 @@ "post": { "operationId": "mcp-read-server-get", "summary": "查看 MCP 服务器详情", - "description": "返回单个 MCP 服务器的完整配置，并附带实时工具清单。", + "description": "查看单个 MCP 服务器并实时探测其工具列表。", "tags": [ "AI SRE/MCP 服务器" ], @@ -21297,7 +21246,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 该接口会发起实时工具探测；探测失败时填充 `list_error` 字段，而不会导致整个请求失败。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 详情接口会实时探测工具；探测失败时设置 `list_error`，请求本身仍成功。\n", "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-read-server-get", "metadata": { "sidebarTitle": "查看 MCP 服务器详情" @@ -21326,39 +21275,32 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "server_id": "mcp-2b5e8d14a7c9", + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", "account_id": 10023, "team_id": 0, "can_edit": true, - "server_name": "GitHub Tools", - "description": "Read issues and pull requests from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, + "server_name": "prometheus", + "description": "Query Prometheus metrics and alerts.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", "status": "enabled", "connect_timeout": 10, - "call_timeout": 30, - "tool_count": 12, - "auth_mode": "shared", - "created_by": 80011, - "created_at": 1716960000000, - "updated_at": 1717046400000, + "call_timeout": 60, + "tool_count": 2, "tools": [ { - "name": "list_issues", - "description": "List issues in a repository." + "name": "query", + "description": "Run a PromQL instant query." }, { - "name": "get_pull_request", - "description": "Fetch a pull request by number." + "name": "query_range", + "description": "Run a PromQL range query." } - ] + ], + "auth_mode": "shared", + "created_by": 80011, + "created_at": 1716960000000, + "updated_at": 1717046400000 } } } @@ -21385,7 +21327,7 @@ "$ref": "#/components/schemas/MCPServerGetRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9" + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1" } } } @@ -21396,7 +21338,7 @@ "post": { "operationId": "mcp-write-server-update", "summary": "更新 MCP 服务器", - "description": "编辑 MCP 服务器的连接设置或重新指定其所属团队。", + "description": "更新 MCP 服务器配置；省略字段表示不变。", "tags": [ "AI SRE/MCP 服务器" ], @@ -21406,7 +21348,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 内置 MCP 服务器为只读，无法修改。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `env`/`headers` 中的脱敏密钥会被保留——回传脱敏值不会覆盖已存储的真实密钥。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-update", "metadata": { "sidebarTitle": "更新 MCP 服务器" @@ -21435,25 +21377,28 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "server_id": "mcp-2b5e8d14a7c9", + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", "account_id": 10023, "team_id": 0, "can_edit": true, - "server_name": "GitHub Tools", - "description": "Read issues, PRs, and commits from GitHub.", - "transport": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], - "env": { - "GITHUB_TOKEN": "ghp_xxx" - }, + "server_name": "prometheus", + "description": "Query Prometheus metrics, alerts, and rules.", + "transport": "streamable-http", + "url": "https://mcp.example.com/prometheus", "status": "enabled", "connect_timeout": 10, - "call_timeout": 30, - "tool_count": 12, + "call_timeout": 60, + "tool_count": 2, + "tools": [ + { + "name": "query", + "description": "Run a PromQL instant query." + }, + { + "name": "query_range", + "description": "Run a PromQL range query." + } + ], "auth_mode": "shared", "created_by": 80011, "created_at": 1716960000000, @@ -21469,6 +21414,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21484,8 +21432,8 @@ "$ref": "#/components/schemas/MCPServerUpdateRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9", - "description": "Read issues, PRs, and commits from GitHub." + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1", + "description": "Query Prometheus metrics, alerts, and rules." } } } @@ -21496,7 +21444,7 @@ "post": { "operationId": "mcp-write-server-delete", "summary": "删除 MCP 服务器", - "description": "永久删除 MCP 服务器，使智能体无法再使用其工具。", + "description": "按 ID 删除 MCP 服务器。", "tags": [ "AI SRE/MCP 服务器" ], @@ -21506,7 +21454,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 内置 MCP 服务器为只读，无法删除。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-delete", "metadata": { "sidebarTitle": "删除 MCP 服务器" @@ -21527,14 +21475,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -21545,6 +21494,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21560,7 +21512,7 @@ "$ref": "#/components/schemas/MCPServerDeleteRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9" + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1" } } } @@ -21571,7 +21523,7 @@ "post": { "operationId": "mcp-write-server-enable", "summary": "启用 MCP 服务器", - "description": "启用已禁用的 MCP 服务器，使智能体可调用其工具。", + "description": "启用已禁用的 MCP 服务器。", "tags": [ "AI SRE/MCP 服务器" ], @@ -21581,7 +21533,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 内置 MCP 服务器为只读；若服务器已启用则返回 InvalidParameter。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-enable", "metadata": { "sidebarTitle": "启用 MCP 服务器" @@ -21602,14 +21554,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -21620,6 +21573,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21635,7 +21591,7 @@ "$ref": "#/components/schemas/MCPServerStatusRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9" + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1" } } } @@ -21646,7 +21602,7 @@ "post": { "operationId": "mcp-write-server-disable", "summary": "禁用 MCP 服务器", - "description": "禁用 MCP 服务器，使智能体停止调用其工具。", + "description": "禁用已启用的 MCP 服务器。", "tags": [ "AI SRE/MCP 服务器" ], @@ -21656,7 +21612,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 内置 MCP 服务器为只读；若服务器已禁用则返回 InvalidParameter。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **MCP 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/mcp-servers/mcp-write-server-disable", "metadata": { "sidebarTitle": "禁用 MCP 服务器" @@ -21677,14 +21633,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -21695,6 +21652,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21710,7 +21670,7 @@ "$ref": "#/components/schemas/MCPServerStatusRequest" }, "example": { - "server_id": "mcp-2b5e8d14a7c9" + "server_id": "mcp_4kP9wQ2nLceRtY7uVb3xA1" } } } @@ -21721,7 +21681,7 @@ "post": { "operationId": "remote-agent-write-create", "summary": "创建 A2A 智能体", - "description": "注册一个新的 A2A 远程智能体，供 SRE 智能体委派任务。", + "description": "通过智能体卡片 URL 注册新的 A2A 远程智能体。", "tags": [ "AI SRE/A2A 智能体" ], @@ -21731,7 +21691,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 创建时会拉取并校验 `card_url` 上的 agent card；若无法访问则返回 InvalidParameter。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- `card_url` 必须可解析为有效的智能体卡片；无法访问或无效的卡片返回 InvalidParameter。\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-create", "metadata": { "sidebarTitle": "创建 A2A 智能体" @@ -21760,7 +21720,7 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -21772,6 +21732,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -21787,13 +21750,9 @@ "$ref": "#/components/schemas/A2AAgentCreateRequest" }, "example": { - "agent_name": "Network Diagnostics Agent", - "card_url": "https://agents.example.com/network-diag/.well-known/agent.json", - "description": "Runs traceroute and BGP-path analysis for network incidents.", + "agent_name": "deploy-bot", + "card_url": "https://agents.example.com/deploy-bot/card", "auth_type": "bearer", - "auth_config": { - "token": "secret" - }, "streaming": true, "team_id": 0 } @@ -21816,7 +21775,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `offset`/`limit`（而非 `p`/`limit`）。\n", "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-read-list", "metadata": { "sidebarTitle": "查询 A2A 智能体列表" @@ -21847,30 +21806,27 @@ "data": { "items": [ { - "agent_id": "a2a_9d4c1f60b3a2", + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D", "account_id": 10023, "team_id": 0, "can_edit": true, - "agent_name": "Network Diagnostics Agent", - "description": "Runs traceroute and BGP-path analysis for network incidents.", - "card_url": "https://agents.example.com/network-diag/.well-known/agent.json", + "agent_name": "deploy-bot", + "description": "Remote agent that inspects deployment pipelines.", + "card_url": "https://agents.example.com/deploy-bot/card", "auth_type": "bearer", - "auth_config": { - "token": "secret" - }, "streaming": true, "status": "enabled", - "agent_card_name": "network-diag", + "agent_card_name": "Deploy Bot", "agent_card_skills": [ - "traceroute", - "bgp-analysis" + "rollback", + "diff" ], "card_resolve_timeout": 10, "task_timeout": 120, "auth_mode": "shared", "created_by": 80011, - "created_at": 1716960000, - "updated_at": 1717046400 + "created_at": 1716960000000, + "updated_at": 1717046400000 } ], "total": 1 @@ -21913,7 +21869,7 @@ "post": { "operationId": "remote-agent-read-get", "summary": "查看 A2A 智能体详情", - "description": "按 ID 返回单个 A2A 智能体的完整配置。", + "description": "按 ID 查看单个 A2A 智能体。", "tags": [ "AI SRE/A2A 智能体" ], @@ -21952,30 +21908,27 @@ "example": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "data": { - "agent_id": "a2a_9d4c1f60b3a2", + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D", "account_id": 10023, "team_id": 0, "can_edit": true, - "agent_name": "Network Diagnostics Agent", - "description": "Runs traceroute and BGP-path analysis for network incidents.", - "card_url": "https://agents.example.com/network-diag/.well-known/agent.json", + "agent_name": "deploy-bot", + "description": "Remote agent that inspects deployment pipelines.", + "card_url": "https://agents.example.com/deploy-bot/card", "auth_type": "bearer", - "auth_config": { - "token": "secret" - }, "streaming": true, "status": "enabled", - "agent_card_name": "network-diag", + "agent_card_name": "Deploy Bot", "agent_card_skills": [ - "traceroute", - "bgp-analysis" + "rollback", + "diff" ], "card_resolve_timeout": 10, "task_timeout": 120, "auth_mode": "shared", "created_by": 80011, - "created_at": 1716960000, - "updated_at": 1717046400 + "created_at": 1716960000000, + "updated_at": 1717046400000 } } } @@ -22002,7 +21955,7 @@ "$ref": "#/components/schemas/A2AAgentIDRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -22013,7 +21966,7 @@ "post": { "operationId": "remote-agent-write-update", "summary": "更新 A2A 智能体", - "description": "编辑 A2A 智能体的 card URL、鉴权、流式开关或所属团队。", + "description": "对 A2A 智能体执行部分更新；省略字段表示不变。", "tags": [ "AI SRE/A2A 智能体" ], @@ -22023,7 +21976,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 省略某字段即保持不变；仅请求中出现的字段会被更新。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-update", "metadata": { "sidebarTitle": "更新 A2A 智能体" @@ -22044,14 +21997,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -22062,6 +22016,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -22077,8 +22034,8 @@ "$ref": "#/components/schemas/A2AAgentUpdateRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2", - "description": "Runs traceroute, BGP, and DNS analysis for network incidents." + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D", + "description": "Inspects deployment pipelines and proposes rollbacks." } } } @@ -22089,7 +22046,7 @@ "post": { "operationId": "remote-agent-write-enable", "summary": "启用 A2A 智能体", - "description": "启用已禁用的 A2A 智能体，使 SRE 智能体可向其委派任务。", + "description": "启用已禁用的 A2A 智能体。", "tags": [ "AI SRE/A2A 智能体" ], @@ -22099,7 +22056,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若智能体已启用则返回 InvalidParameter。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-enable", "metadata": { "sidebarTitle": "启用 A2A 智能体" @@ -22120,14 +22077,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -22138,6 +22096,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -22153,7 +22114,7 @@ "$ref": "#/components/schemas/A2AAgentIDRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -22164,7 +22125,7 @@ "post": { "operationId": "remote-agent-write-disable", "summary": "禁用 A2A 智能体", - "description": "禁用 A2A 智能体，使 SRE 智能体停止向其委派任务。", + "description": "禁用已启用的 A2A 智能体。", "tags": [ "AI SRE/A2A 智能体" ], @@ -22174,7 +22135,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 若智能体已禁用则返回 InvalidParameter。\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-disable", "metadata": { "sidebarTitle": "禁用 A2A 智能体" @@ -22195,14 +22156,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -22213,6 +22175,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -22228,7 +22193,7 @@ "$ref": "#/components/schemas/A2AAgentIDRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -22239,7 +22204,7 @@ "post": { "operationId": "remote-agent-write-delete", "summary": "删除 A2A 智能体", - "description": "软删除 A2A 智能体注册，使其不再可用。", + "description": "按 ID 软删除 A2A 智能体。", "tags": [ "AI SRE/A2A 智能体" ], @@ -22249,7 +22214,7 @@ } ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 每次调用都会记入账户审计日志。\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **Agent 管理**（`ai-sre`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志。\n", "href": "/zh/api-reference/ai-sre/a2a-agents/remote-agent-write-delete", "metadata": { "sidebarTitle": "删除 A2A 智能体" @@ -22270,14 +22235,15 @@ "properties": { "data": { "type": "null", - "description": "No payload; the operation returns an empty data field on success." + "description": "成功时恒为 null。" } } } ] }, "example": { - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null } } } @@ -22288,6 +22254,9 @@ "401": { "$ref": "#/components/responses/Unauthorized" }, + "403": { + "$ref": "#/components/responses/Forbidden" + }, "429": { "$ref": "#/components/responses/TooManyRequests" }, @@ -22303,7 +22272,7 @@ "$ref": "#/components/schemas/A2AAgentIDRequest" }, "example": { - "agent_id": "a2a_9d4c1f60b3a2" + "agent_id": "a2a_6mWqZ2pK9nLcR3tY8uVb4D" } } } @@ -22314,7 +22283,7 @@ "post": { "operationId": "session-read-list", "summary": "查询会话列表", - "description": "分页查询调用者在所属账户内可见的智能体会话，可按应用、入口来源、归档状态与团队范围过滤。读取范围限定为 app_key 解析出的人员可见范围。", + "description": "分页查询调用者可见的智能体会话，可按应用、入口、归档状态与团队过滤。", "tags": [ "AI SRE/会话" ], @@ -22324,28 +22293,12 @@ } ], "x-mint": { - "content": "## 使用限制\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 频率限制 | 每个账户 **每分钟 1,000 次**；**每秒 50 次** |\n| 权限 | 无 —— 任意有效 `app_key` 均可调用 |\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 分页使用 `p`/`limit`（最大 100）；`scope` 默认 `all`（本人 + 所属团队）。\n- `is_running` 反映实时运行集合；`has_unread` 按调用者各自计算。\n", "href": "/zh/api-reference/ai-sre/sessions/session-read-list", "metadata": { "sidebarTitle": "查询会话列表" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionListRequest" - }, - "example": { - "app_name": "ai-sre", - "limit": 2, - "orderby": "updated_at", - "scope": "all" - } - } - } - }, "responses": { "200": { "description": "Success", @@ -22416,6 +22369,22 @@ "500": { "$ref": "#/components/responses/ServerError" } + }, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionListRequest" + }, + "example": { + "app_name": "ai-sre", + "limit": 2, + "orderby": "updated_at", + "scope": "all" + } + } + } } } }, @@ -22423,7 +22392,7 @@ "post": { "operationId": "session-read-info", "summary": "查看会话详情", - "description": "查看单个会话详情，并返回其最近事件的一页（向更早方向分页）。使用 search_after_ctx 翻阅更早的历史。", + "description": "查看单个会话，并返回其最近事件的一页（向更早方向分页）。", "tags": [ "AI SRE/会话" ], @@ -22433,26 +22402,12 @@ } ], "x-mint": { - "content": "## 使用限制\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 频率限制 | 每个账户 **每分钟 1,000 次**；**每秒 50 次** |\n| 权限 | 无 —— 任意有效 `app_key` 均可调用 |\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 使用上一次响应的 `search_after_ctx` 翻阅更早的历史。\n- `limit`（或旧版 `num_recent_events`）限制事件页大小；默认 100，最大 1000。\n", "href": "/zh/api-reference/ai-sre/sessions/session-read-info", "metadata": { "sidebarTitle": "查看会话详情" } }, - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SessionGetRequest" - }, - "example": { - "session_id": "sess_f8oDvqiG64uur6sBNsTc4u", - "num_recent_events": 50 - } - } - } - }, "responses": { "200": { "description": "Success", @@ -22543,15 +22498,26 @@ "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/SessionGetRequest" + }, + "example": { + "session_id": "sess_f8oDvqiG64uur6sBNsTc4u", + "num_recent_events": 50 + } + } + } } } }, @@ -22559,7 +22525,7 @@ "post": { "operationId": "session-read-export", "summary": "导出会话记录", - "description": "以 NDJSON（application/x-ndjson）流式导出会话的完整事件记录，每行一个 JSON 对象。第一行始终为 session_meta 信封，其后为会话事件（见 ExportLine）。请逐行解析并写入文件，切勿将整段记录全部读入内存。include_subagents 为 true 时，每条 subagent_dispatch 行后会跟随子会话自身的事件流。", + "description": "以换行分隔的 JSON（NDJSON）流式导出会话的完整事件记录。", "tags": [ "AI SRE/会话" ], @@ -22569,12 +22535,37 @@ } ], "x-mint": { - "content": "## 使用限制\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 频率限制 | 每个账户 **每分钟 1,000 次**；**每秒 50 次** |\n| 权限 | 无 —— 任意有效 `app_key` 均可调用 |\n", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 响应为 `application/x-ndjson`——请逐行解析并写入文件，切勿将整段记录读入内存。\n- 第一行始终为 `session_meta` 信封；`include_subagents=true` 会在派发行后内联各子会话的事件流。\n", "href": "/zh/api-reference/ai-sre/sessions/session-read-export", "metadata": { "sidebarTitle": "导出会话记录" } }, + "responses": { + "200": { + "description": "流式 NDJSON（application/x-ndjson）。每行一个 JSON 对象，以换行结束。第一行始终为 `session_meta` 信封，其后为会话事件。", + "content": { + "application/x-ndjson": { + "schema": { + "type": "string", + "description": "换行分隔的 JSON 流。请逐行解析，切勿缓冲整个响应体。" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/ServerError" + } + }, "requestBody": { "required": true, "content": { @@ -22588,17 +22579,54 @@ } } } + } + } + }, + "/safari/session/delete": { + "post": { + "operationId": "session-write-delete", + "summary": "删除会话", + "description": "按 ID 删除会话。", + "tags": [ + "AI SRE/会话" + ], + "security": [ + { + "AppKeyAuth": [] + } + ], + "x-mint": { + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个 `app_key` **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无 —— 持有有效的 `app_key` 即可调用 |\n\n## 使用说明\n\n- 需要对该会话拥有管理权限（创建者、账户管理员或所属团队成员）。\n", + "href": "/zh/api-reference/ai-sre/sessions/session-write-delete", + "metadata": { + "sidebarTitle": "删除会话" + } }, "responses": { "200": { - "description": "Streaming NDJSON (application/x-ndjson). One JSON object per line, terminated by a newline. The first line is always a `session_meta` envelope; subsequent lines are session events (see ExportLine).", + "description": "Success", "content": { - "application/x-ndjson": { + "application/json": { "schema": { - "type": "string", - "description": "Newline-delimited JSON stream. Parse line-by-line; do not buffer the whole body. Each line decodes to an ExportLine object — see #/components/schemas/ExportLine." + "allOf": [ + { + "$ref": "#/components/schemas/ResponseEnvelope" + }, + { + "type": "object", + "properties": { + "data": { + "type": "null", + "description": "成功时恒为 null。" + } + } + } + ] }, - "example": "{\"type\":\"session_meta\",\"session_id\":\"sess_f8oDvqiG64uur6sBNsTc4u\",\"account_id\":2451002751131,\"app_name\":\"ai-sre\",\"started_at\":\"2026-06-02T02:39:31.228Z\",\"ended_at\":\"2026-06-02T02:39:53.457Z\",\"model\":\"deepseek-v4-pro\"}\n{\"type\":\"user_message\",\"seq\":1,\"ts\":\"2026-06-02T02:39:31.241Z\"}\n{\"type\":\"user_message\",\"seq\":2,\"ts\":\"2026-06-02T02:39:31.245Z\",\"content\":\" ... \"}\n{\"type\":\"final_answer\",\"seq\":3,\"ts\":\"2026-06-02T02:39:53.457Z\",\"content\":\"## Conclusion: noise alert, not a real incident ...\"}\n" + "example": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": null + } } } }, @@ -22608,15 +22636,25 @@ "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/SessionDeleteRequest" + }, + "example": { + "session_id": "sess_f8oDvqiG64uur6sBNsTc4u" + } + } + } } } } @@ -22632,7 +22670,7 @@ }, "responses": { "BadRequest": { - "description": "请求非法 — 通常是参数缺失或格式不正确。", + "description": "Invalid request — usually a missing or malformed parameter.", "content": { "application/json": { "schema": { @@ -22640,11 +22678,12 @@ }, "examples": { "missingParameter": { + "summary": "Missing required parameter", "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { "code": "InvalidParameter", - "message": "The specified parameter is not valid." + "message": "The specified parameter skill_id is not valid." } } } @@ -22653,7 +22692,7 @@ } }, "Unauthorized": { - "description": "app_key 缺失或无效。", + "description": "Missing or invalid app_key.", "content": { "application/json": { "schema": { @@ -22674,14 +22713,14 @@ } }, "Forbidden": { - "description": "app_key 有效但没有执行该操作的权限。", + "description": "The app_key is valid but lacks permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { - "noEditPermission": { + "accessDenied": { "value": { "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", "error": { @@ -22716,7 +22755,7 @@ } }, "TooManyRequests": { - "description": "命中限流。可能是全局 API 限流、账户级限流或集成级限流。限流按账户聚合。", + "description": "Rate limit hit. Either the global API limit or a per-account limit.", "content": { "application/json": { "schema": { @@ -22737,7 +22776,7 @@ } }, "ServerError": { - "description": "服务端未预期错误。反馈问题时请携带 request_id。", + "description": "Unexpected server-side error. Include the request_id when reporting.", "content": { "application/json": { "schema": { @@ -22761,7 +22800,7 @@ "schemas": { "ErrorCode": { "type": "string", - "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |", + "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational.", "enum": [ "OK", "InvalidParameter", @@ -22783,42 +22822,18 @@ "DangerousOperation", "InternalError", "ServiceUnavailable" - ], - "x-enumDescriptions": { - "OK": "保留值，正常错误响应不会返回。", - "InvalidParameter": "必填参数缺失或未通过校验。", - "BadRequest": "通用的 400 错误，通常是请求本身不合法。", - "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。", - "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。", - "NoLicense": "功能需要有效授权，但未找到可用的 license。", - "ReferenceExist": "该资源仍被其他实体引用，无法删除。", - "Unauthorized": "`app_key` 缺失、无效或已过期。", - "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。", - "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。", - "RouteNotFound": "请求的 URL 路径不是已知路由。", - "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。", - "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。", - "RequestLocked": "因连续失败被临时锁定。", - "EntityTooLarge": "请求体超过允许的最大长度。", - "RequestTooFrequently": "命中限流（全局、账户级或集成级）。", - "RequestVerifyRequired": "操作需要二次验证码，但未提供。", - "DangerousOperation": "危险操作，需要进行 MFA 验证。", - "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。", - "ServiceUnavailable": "后端依赖不可用，请稍后重试。" - }, - "example": "InvalidParameter" + ] }, "DutyError": { "type": "object", - "description": "响应结构中的错误 payload，仅在非 2xx 响应时出现。", + "description": "Error payload inside the response envelope. Present only on non-2xx responses.", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", - "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。", - "example": "The specified parameter template_id is not valid." + "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request." } }, "required": [ @@ -22846,7 +22861,7 @@ }, "ErrorResponse": { "type": "object", - "description": "错误响应结构。`error` 必填，`data` 不存在。", + "description": "Response envelope for errors. `error` is required; `data` is absent.", "properties": { "request_id": { "type": "string", @@ -39168,11 +39183,11 @@ }, "MCPServerStatusRequest": { "type": "object", - "description": "Selector for the server whose status is being changed.", + "description": "按 ID 启用/禁用 MCP 服务器。", "properties": { "server_id": { "type": "string", - "description": "Identifier of the target server." + "description": "目标 MCP 服务器 ID。" } }, "required": [ @@ -39181,114 +39196,114 @@ }, "SkillItem": { "type": "object", - "description": "An AI SRE skill — a packaged capability the agent can load at runtime.", + "description": "AI SRE 技能 —— 智能体可加载的 SKILL.md 打包资源。", "properties": { "skill_id": { "type": "string", - "description": "Unique identifier of the skill." + "description": "技能唯一 ID（前缀 `skill_`）。" }, "account_id": { "type": "integer", - "format": "int64", - "description": "Owning account." + "description": "所属账户 ID。", + "format": "int64" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team; 0 means account scope." + "description": "团队范围：0 表示账户级；>0 表示所属团队。", + "format": "int64" }, "skill_name": { "type": "string", - "description": "Name of the skill, parsed from its SKILL.md frontmatter." + "description": "技能名称，在账户内唯一。" }, "description": { "type": "string", - "description": "What the skill does and when the agent should use it." + "description": "来自 SKILL.md frontmatter 的可读描述。" }, "content": { "type": "string", - "description": "Full SKILL.md body; omitted in list responses." + "description": "完整的 SKILL.md 内容；列表响应中省略。" }, "version": { "type": "string", - "description": "Skill version string from its frontmatter." + "description": "frontmatter 中的技能版本。" }, "tags": { "type": "array", "items": { "type": "string" }, - "description": "Tags declared in the skill frontmatter." + "description": "从 frontmatter 解析的标签。" }, "author": { "type": "string", - "description": "Author declared in the skill frontmatter." + "description": "技能作者。" }, "license": { "type": "string", - "description": "License declared in the skill frontmatter." + "description": "技能许可证。" }, "tools": { "type": "array", "items": { "type": "string" }, - "description": "Tools the skill requires, declared in its frontmatter." + "description": "所需工具（内置或 `mcp:server/tool`）。" }, "s3_key": { "type": "string", - "description": "Object-storage key of the skill's zip package." + "description": "技能压缩包在对象存储中的 key。" }, "checksum": { "type": "string", - "description": "SHA-256 checksum of the skill's zip package." + "description": "技能压缩包的 SHA-256 校验和。" }, "status": { "type": "string", + "description": "技能状态。", "enum": [ "enabled", "disabled" - ], - "description": "Whether the skill is active and loadable by agents." + ] }, "created_by": { "type": "integer", - "format": "int64", - "description": "Member who created this resource." + "description": "创建该技能的成员 ID。", + "format": "int64" }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation time as a Unix timestamp in milliseconds." + "description": "创建时间，Unix 毫秒时间戳。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last-update time as a Unix timestamp in milliseconds." + "description": "最近更新时间，Unix 毫秒时间戳。" }, "can_edit": { "type": "boolean", - "description": "Whether the calling member may edit or delete this resource." + "description": "调用者是否可编辑该技能。" }, "source_template_name": { "type": "string", - "description": "Marketplace template this skill was installed from, if any." + "description": "该技能安装来源的市场模板名称；自建技能为空。" }, "source_template_version": { "type": "string", - "description": "Marketplace template version captured at install time." + "description": "安装时的模板版本。" }, "update_available": { "type": "boolean", - "description": "A newer marketplace template version exists for this skill." + "description": "当市场存在更新版本时为 true。" }, "is_modified": { "type": "boolean", - "description": "A marketplace-sourced skill has been edited locally; auto-update skips it." + "description": "当市场来源技能被本地修改时为 true（自动更新将跳过）。" }, "created": { "type": "boolean", - "description": "Install response only: true for a fresh install, false for an in-place upsert." + "description": "仅在“从会话安装”响应中出现：true 表示新建，false 表示原地更新。" } }, "required": [ @@ -39492,15 +39507,17 @@ }, "A2AAgentListRequest": { "type": "object", - "description": "Filters for listing A2A agents.", + "description": "A2A 智能体列表的分页与团队过滤条件。", "properties": { "offset": { "type": "integer", - "description": "Number of rows to skip for pagination." + "description": "分页行偏移。", + "default": 0 }, "limit": { "type": "integer", - "description": "Maximum number of rows to return; defaults to 20." + "description": "每页数量。", + "default": 20 }, "team_ids": { "type": "array", @@ -39508,31 +39525,37 @@ "type": "integer", "format": "int64" }, - "description": "Restrict results to resources owned by these teams; intersected with the caller's visible set." + "description": "按团队 ID 过滤；为空则使用调用者可见范围。" }, "include_account": { - "type": "boolean", - "description": "Include account-scoped rows alongside team-scoped ones; defaults to true." + "type": [ + "boolean", + "null" + ], + "description": "是否包含账户级（team_id=0）记录，默认 true。" } } }, "SkillUpdateRequest": { "type": "object", - "description": "Editable fields of a skill.", + "description": "可编辑的技能元数据。", "properties": { "skill_id": { "type": "string", - "description": "Identifier of the skill to update." + "description": "目标技能 ID。" }, "description": { "type": "string", - "maxLength": 1024, - "description": "New description for the skill." + "description": "新的描述。", + "maxLength": 1024 }, "team_id": { - "type": "integer", - "format": "int64", - "description": "Reassign the skill to this team; omit to leave unchanged, 0 for account scope." + "type": [ + "integer", + "null" + ], + "description": "重新分配团队范围：0 表示账户级；>0 表示团队。省略则不变。", + "format": "int64" } }, "required": [ @@ -39541,19 +39564,19 @@ }, "MCPServerListResponse": { "type": "object", - "description": "Paginated MCP server list.", + "description": "分页的 MCP 服务器列表。", "properties": { "total": { "type": "integer", - "format": "int64", - "description": "Total number of servers matching the filters." + "description": "匹配的服务器总数。", + "format": "int64" }, "servers": { "type": "array", "items": { "$ref": "#/components/schemas/MCPServerItem" }, - "description": "MCP servers on the current page." + "description": "当前页的 MCP 服务器。" } }, "required": [ @@ -39563,137 +39586,146 @@ }, "MCPServerItem": { "type": "object", - "description": "A configured MCP (Model Context Protocol) server the agent can call tools through.", + "description": "账户下注册的 MCP 服务器（连接器）。", "properties": { "server_id": { "type": "string", - "description": "Unique identifier of the MCP server." + "description": "MCP 服务器唯一 ID（前缀 `mcp_`）。" }, "account_id": { "type": "integer", - "format": "int64", - "description": "Owning account." + "description": "所属账户 ID。", + "format": "int64" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team; 0 means account scope." + "description": "团队范围：0 表示账户级；>0 表示所属团队。", + "format": "int64" }, "can_edit": { "type": "boolean", - "description": "Whether the calling member may edit or delete this resource." + "description": "调用者是否可编辑该服务器。" }, "server_name": { "type": "string", - "description": "Display name of the MCP server." + "description": "MCP 服务器名称，在账户内唯一。" }, "description": { "type": "string", - "description": "What this MCP server provides." + "description": "服务器描述。" }, "ai_description": { "type": "string", - "description": "LLM-generated description, preferred over description when present." + "description": "LLM 生成的描述，存在时优先于 `description`。" }, "transport": { "type": "string", + "description": "传输协议。", "enum": [ "stdio", "sse", "streamable-http" - ], - "description": "Transport used to reach the server." + ] }, "command": { "type": "string", - "description": "Executable launched for stdio transport." + "description": "可执行命令（仅 stdio 传输）。" }, "args": { "type": "array", "items": { "type": "string" }, - "description": "Command-line arguments for the stdio executable." + "description": "命令参数（stdio 传输）。" }, "env": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Environment variables passed to the stdio process." + "description": "环境变量（stdio 传输）；密钥值已脱敏。" }, "url": { "type": "string", - "description": "Endpoint URL for sse or streamable-http transport." + "description": "服务器 URL（sse / streamable-http 传输）。" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "HTTP headers sent to the remote endpoint; secret values are masked." + "description": "HTTP 头（sse / streamable-http）；密钥值已脱敏。" }, "proxy_url": { "type": "string", - "description": "Outbound proxy URL used to reach the server." + "description": "访问服务器使用的出站代理 URL。" }, "status": { "type": "string", + "description": "服务器状态。", "enum": [ "enabled", "disabled" - ], - "description": "Whether the server is active and usable by agents." + ] }, "connect_timeout": { "type": "integer", - "description": "Connection timeout in seconds." + "description": "连接超时，单位秒（0 表示默认 10 秒）。" }, "call_timeout": { "type": "integer", - "description": "Per-call timeout in seconds." + "description": "工具调用超时，单位秒（0 表示默认 60 秒）。" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/MCPToolInfo" }, - "description": "Live tool catalogue; populated only by get and test." + "description": "实时工具列表；由 get/test 接口填充。" }, "tool_count": { "type": "integer", - "description": "Number of tools discovered on the server." + "description": "实时工具列表的数量。" }, "list_error": { "type": "string", - "description": "Tool-probe failure message; present when the live probe failed." + "description": "实时获取工具列表失败时的错误信息。" }, "auth_mode": { "type": "string", - "description": "Credential model: shared, per_user_secret, or per_user_oauth." + "description": "认证模式。", + "enum": [ + "shared", + "per_user_secret", + "per_user_oauth" + ] }, "secret_schema": { "type": "string", - "description": "JSON schema of the per-user secret." + "description": "JSON 编码的密钥 schema（per_user_secret 模式）。" }, "oauth_metadata": { "type": "string", - "description": "OAuth metadata JSON." + "description": "JSON 编码的 OAuth 元数据（per_user_oauth 模式）。" + }, + "source_template_name": { + "type": "string", + "description": "该连接器安装来源的市场模板名称；自建为空。" }, "created_by": { "type": "integer", - "format": "int64", - "description": "Member who created this resource." + "description": "创建该服务器的成员 ID。", + "format": "int64" }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation time as a Unix timestamp in milliseconds." + "description": "创建时间，Unix 毫秒时间戳。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last-update time as a Unix timestamp in milliseconds." + "description": "最近更新时间，Unix 毫秒时间戳。" } }, "required": [ @@ -39714,18 +39746,20 @@ }, "MCPToolInfo": { "type": "object", - "description": "Metadata for a single tool exposed by an MCP server.", + "description": "MCP 服务器暴露的单个工具的元数据。", "properties": { "name": { "type": "string", - "description": "Tool name as advertised by the server." + "description": "工具名称。" }, "description": { "type": "string", - "description": "What the tool does." + "description": "工具描述。" }, "input_schema": { - "description": "JSON schema of the tool's input arguments." + "type": "object", + "additionalProperties": true, + "description": "描述工具输入参数的 JSON Schema。" } }, "required": [ @@ -39733,19 +39767,6 @@ "description" ] }, - "SkillDownloadRequest": { - "type": "object", - "description": "Selector for the skill to download.", - "properties": { - "skill_id": { - "type": "string", - "description": "Identifier of the skill to download." - } - }, - "required": [ - "skill_id" - ] - }, "GetWarRoomDefaultObserversResponse": { "type": "object", "properties": { @@ -39819,11 +39840,11 @@ }, "SkillDeleteRequest": { "type": "object", - "description": "Selector for the skill to delete.", + "description": "按 ID 删除技能。", "properties": { "skill_id": { "type": "string", - "description": "Identifier of the skill to delete." + "description": "目标技能 ID。" } }, "required": [ @@ -39832,11 +39853,11 @@ }, "MCPServerGetRequest": { "type": "object", - "description": "Selector for a single MCP server.", + "description": "按 ID 查询 MCP 服务器。", "properties": { "server_id": { "type": "string", - "description": "Identifier of the server to fetch." + "description": "目标 MCP 服务器 ID。" } }, "required": [ @@ -39862,11 +39883,11 @@ }, "SkillGetRequest": { "type": "object", - "description": "Selector for a single skill.", + "description": "按 ID 查询技能。", "properties": { "skill_id": { "type": "string", - "description": "Identifier of the skill to fetch." + "description": "目标技能 ID。" } }, "required": [ @@ -39875,19 +39896,19 @@ }, "SkillListResponse": { "type": "object", - "description": "Paginated skill list.", + "description": "分页的技能列表。", "properties": { "total": { "type": "integer", - "format": "int64", - "description": "Total number of skills matching the filters." + "description": "匹配的技能总数。", + "format": "int64" }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/SkillItem" }, - "description": "Skills on the current page." + "description": "当前页的技能。" } }, "required": [ @@ -39984,11 +40005,11 @@ }, "SkillStatusRequest": { "type": "object", - "description": "Selector for the skill whose status is being changed.", + "description": "按 ID 启用/禁用技能。", "properties": { "skill_id": { "type": "string", - "description": "Identifier of the target skill." + "description": "目标技能 ID。" } }, "required": [ @@ -39997,90 +40018,95 @@ }, "MCPServerCreateRequest": { "type": "object", - "description": "Configuration for a new MCP server.", + "description": "新建 MCP 服务器的配置。", "properties": { "server_name": { "type": "string", + "description": "MCP 服务器名称，在账户内唯一。", "minLength": 1, - "maxLength": 255, - "description": "Display name of the server." + "maxLength": 255 }, "description": { "type": "string", + "description": "服务器描述。", "minLength": 1, - "maxLength": 1024, - "description": "What this MCP server provides." + "maxLength": 1024 }, "transport": { "type": "string", + "description": "传输协议。", "enum": [ "stdio", "sse", "streamable-http" - ], - "description": "Transport used to reach the server." + ] }, "command": { "type": "string", - "description": "Executable to launch for stdio transport." + "description": "可执行命令（stdio 传输）。" }, "args": { "type": "array", "items": { "type": "string" }, - "description": "Command-line arguments for the stdio executable." + "description": "命令参数（stdio 传输）。" }, "env": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Environment variables for the stdio process." + "description": "环境变量（stdio 传输）。" }, "url": { "type": "string", - "description": "Endpoint URL for sse or streamable-http transport." + "description": "服务器 URL（sse / streamable-http 传输）。" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "HTTP headers sent to the remote endpoint." + "description": "HTTP 头（sse / streamable-http）。" }, "connect_timeout": { "type": "integer", - "description": "Connection timeout in seconds." + "description": "连接超时，单位秒。0 表示默认（10 秒）。" }, "call_timeout": { "type": "integer", - "description": "Per-call timeout in seconds." + "description": "工具调用超时，单位秒。0 表示默认（60 秒）。" + }, + "auth_mode": { + "type": "string", + "description": "认证模式：shared（默认）、per_user_secret 或 per_user_oauth。" + }, + "secret_schema": { + "type": "string", + "description": "JSON 密钥 schema；auth_mode=per_user_secret 时必填。" + }, + "oauth_metadata": { + "type": "string", + "description": "JSON OAuth 元数据；为 per_user_oauth 预留。" }, "status": { "type": "string", + "description": "初始状态。", "enum": [ "enabled", "disabled" ], - "description": "Initial lifecycle state of the server." + "default": "enabled" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team for the new server; 0 for account scope." - }, - "auth_mode": { - "type": "string", - "description": "Credential model; defaults to shared." - }, - "secret_schema": { - "type": "string", - "description": "JSON schema of the per-user secret; required when auth_mode is per_user_secret." + "description": "团队范围：0 表示账户级；>0 表示团队。", + "format": "int64" }, - "oauth_metadata": { + "source_template_name": { "type": "string", - "description": "OAuth metadata JSON; reserved for OAuth-based auth." + "description": "从连接器模板创建时的市场模板名称。" } }, "required": [ @@ -40091,11 +40117,11 @@ }, "MCPServerDeleteRequest": { "type": "object", - "description": "Selector for the server to delete.", + "description": "按 ID 删除 MCP 服务器。", "properties": { "server_id": { "type": "string", - "description": "Identifier of the server to delete." + "description": "目标 MCP 服务器 ID。" } }, "required": [ @@ -40104,15 +40130,17 @@ }, "SkillListRequest": { "type": "object", - "description": "Filters for listing skills.", + "description": "技能列表的分页与团队过滤条件。", "properties": { "p": { "type": "integer", - "description": "Page number, starting at 1." + "description": "页码，从 1 开始。", + "default": 1 }, "limit": { "type": "integer", - "description": "Page size; defaults to 20." + "description": "每页数量。", + "default": 20 }, "team_ids": { "type": "array", @@ -40120,96 +40148,102 @@ "type": "integer", "format": "int64" }, - "description": "Restrict results to resources owned by these teams; intersected with the caller's visible set." + "description": "按团队 ID 过滤；为空则使用调用者可见范围。" }, "include_account": { - "type": "boolean", - "description": "Include account-scoped rows alongside team-scoped ones; defaults to true." + "type": [ + "boolean", + "null" + ], + "description": "是否包含账户级（team_id=0）记录，默认 true。" } } }, "MCPServerUpdateRequest": { "type": "object", - "description": "Editable fields of an MCP server; omitted fields are left unchanged.", + "description": "MCP 服务器的部分更新；省略字段表示不变。", "properties": { "server_id": { "type": "string", - "description": "Identifier of the server to update." + "description": "目标 MCP 服务器 ID。" }, "server_name": { "type": "string", + "description": "新名称。", "minLength": 1, - "maxLength": 255, - "description": "New display name." + "maxLength": 255 }, "description": { "type": "string", + "description": "新描述。", "minLength": 1, - "maxLength": 1024, - "description": "New description." + "maxLength": 1024 }, "transport": { "type": "string", + "description": "传输协议。", "enum": [ "stdio", "sse", "streamable-http" - ], - "description": "New transport for the server." + ] }, "command": { "type": "string", - "description": "New stdio executable." + "description": "可执行命令（stdio 传输）。" }, "args": { "type": "array", "items": { "type": "string" }, - "description": "New stdio arguments." + "description": "命令参数（stdio 传输）。" }, "env": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "New stdio environment variables." + "description": "环境变量（stdio 传输）。" }, "url": { "type": "string", - "description": "New endpoint URL for remote transports." + "description": "服务器 URL（sse / streamable-http 传输）。" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "New HTTP headers for the remote endpoint." + "description": "HTTP 头（sse / streamable-http）。" }, "connect_timeout": { "type": "integer", - "description": "New connection timeout in seconds." + "description": "连接超时，单位秒。0 表示默认（10 秒）。" }, "call_timeout": { "type": "integer", - "description": "New per-call timeout in seconds." - }, - "team_id": { - "type": "integer", - "format": "int64", - "description": "Reassign the server to this team; omit to leave unchanged, 0 for account scope." + "description": "工具调用超时，单位秒。0 表示默认（60 秒）。" }, "auth_mode": { "type": "string", - "description": "New credential model." + "description": "认证模式：shared（默认）、per_user_secret 或 per_user_oauth。" }, "secret_schema": { "type": "string", - "description": "New per-user secret JSON schema." + "description": "JSON 密钥 schema；auth_mode=per_user_secret 时必填。" }, "oauth_metadata": { "type": "string", - "description": "New OAuth metadata JSON." + "description": "JSON OAuth 元数据；为 per_user_oauth 预留。" + }, + "team_id": { + "type": [ + "integer", + "null" + ], + "description": "重新分配团队范围：0 表示账户级；>0 表示团队。省略则不变。", + "format": "int64" } }, "required": [ @@ -40331,19 +40365,19 @@ }, "A2AAgentListResponse": { "type": "object", - "description": "Paginated A2A agent list.", + "description": "分页的 A2A 智能体列表。", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/A2AAgentItem" }, - "description": "A2A agents on the current page." + "description": "当前页的 A2A 智能体。" }, "total": { "type": "integer", - "format": "int64", - "description": "Total number of agents matching the filters." + "description": "匹配的智能体总数。", + "format": "int64" } }, "required": [ @@ -40353,106 +40387,111 @@ }, "A2AAgentItem": { "type": "object", - "description": "A registered A2A (agent-to-agent) remote agent the SRE agent can delegate to.", + "description": "已注册的 A2A（智能体到智能体）远程智能体。", "properties": { "agent_id": { "type": "string", - "description": "Unique identifier of the A2A agent." + "description": "A2A 智能体唯一 ID（前缀 `a2a_`）。" }, "account_id": { "type": "integer", - "format": "int64", - "description": "Owning account." + "description": "所属账户 ID。", + "format": "int64" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team; 0 means account scope." + "description": "团队范围：0 表示账户级；>0 表示所属团队。", + "format": "int64" }, "can_edit": { "type": "boolean", - "description": "Whether the calling member may edit or delete this resource." + "description": "调用者是否可编辑该智能体。" }, "agent_name": { "type": "string", - "description": "Display name of the agent." + "description": "智能体显示名称。" }, "description": { "type": "string", - "description": "What this agent does and when to delegate to it." + "description": "智能体描述。" }, "card_url": { "type": "string", - "description": "URL of the agent's published A2A agent card." + "description": "远程智能体卡片的 URL。" }, "auth_type": { "type": "string", - "description": "Authentication scheme used when calling the agent." + "description": "访问远程智能体的认证类型。" }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Authentication parameters keyed by name." + "description": "认证配置；密钥值已脱敏。" }, "streaming": { "type": "boolean", - "description": "Whether the agent supports streaming responses." + "description": "远程智能体是否支持流式响应。" }, "status": { "type": "string", + "description": "智能体状态。", "enum": [ "enabled", "disabled" - ], - "description": "Whether the agent is active and reachable." + ] }, "agent_card_name": { "type": "string", - "description": "Name resolved from the fetched agent card." + "description": "从远程卡片解析出的智能体名称。" }, "agent_card_skills": { "type": "array", "items": { "type": "string" }, - "description": "Skills advertised on the fetched agent card." + "description": "远程卡片声明的技能。" }, "card_resolve_timeout": { "type": "integer", - "description": "Timeout for fetching the agent card, in seconds." + "description": "卡片解析超时，单位秒。" }, "task_timeout": { "type": "integer", - "description": "Timeout for a single delegated task, in seconds." + "description": "单任务执行超时，单位秒。" }, "auth_mode": { "type": "string", - "description": "Credential model: shared, per_user_secret, or per_user_oauth." + "description": "认证模式。", + "enum": [ + "shared", + "per_user_secret", + "per_user_oauth" + ] }, "secret_schema": { "type": "string", - "description": "JSON schema of the per-user secret." + "description": "JSON 编码的密钥 schema（per_user_secret 模式）。" }, "oauth_metadata": { "type": "string", - "description": "OAuth metadata JSON." + "description": "JSON 编码的 OAuth 元数据（per_user_oauth 模式）。" }, "created_by": { "type": "integer", - "format": "int64", - "description": "Member who created this resource." + "description": "创建该智能体的成员 ID。", + "format": "int64" }, "created_at": { "type": "integer", "format": "int64", - "description": "Creation time as a Unix timestamp in seconds." + "description": "创建时间，Unix 毫秒时间戳。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "Last-update time as a Unix timestamp in seconds." + "description": "最近更新时间，Unix 毫秒时间戳。" } }, "required": [ @@ -40475,56 +40514,83 @@ }, "A2AAgentUpdateRequest": { "type": "object", - "description": "Editable fields of an A2A agent; omitted fields are left unchanged.", + "description": "A2A 智能体的部分更新；为空或省略的字段保持不变。", "properties": { "agent_id": { "type": "string", - "description": "Identifier of the agent to update." + "description": "目标智能体 ID。" }, "agent_name": { - "type": "string", - "maxLength": 128, - "description": "New display name." + "type": [ + "string", + "null" + ], + "description": "新的显示名称。省略则不变。", + "maxLength": 128 }, "description": { - "type": "string", - "description": "New description." + "type": [ + "string", + "null" + ], + "description": "新的描述。省略则不变。" }, "card_url": { - "type": "string", - "description": "New agent card URL." + "type": [ + "string", + "null" + ], + "description": "新的卡片 URL。省略则不变。" }, "auth_type": { - "type": "string", - "description": "New authentication scheme." + "type": [ + "string", + "null" + ], + "description": "新的认证类型。省略则不变。" }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "New authentication parameters." + "description": "替换认证配置。省略则不变。" }, "streaming": { - "type": "boolean", - "description": "Toggle streaming-response support." + "type": [ + "boolean", + "null" + ], + "description": "切换流式支持。省略则不变。" }, "team_id": { - "type": "integer", - "format": "int64", - "description": "Reassign the agent to this team; omit to leave unchanged, 0 for account scope." + "type": [ + "integer", + "null" + ], + "description": "重新分配团队范围。省略则不变。", + "format": "int64" }, "auth_mode": { - "type": "string", - "description": "New credential model." + "type": [ + "string", + "null" + ], + "description": "新的认证模式：shared、per_user_secret 或 per_user_oauth。" }, "secret_schema": { - "type": "string", - "description": "New per-user secret JSON schema." + "type": [ + "string", + "null" + ], + "description": "新的 JSON 密钥 schema。" }, "oauth_metadata": { - "type": "string", - "description": "New OAuth metadata JSON." + "type": [ + "string", + "null" + ], + "description": "新的 JSON OAuth 元数据。" } }, "required": [ @@ -40533,52 +40599,52 @@ }, "A2AAgentCreateRequest": { "type": "object", - "description": "Configuration for a new A2A agent.", + "description": "注册新 A2A 智能体的参数。", "properties": { "agent_name": { "type": "string", - "maxLength": 128, - "description": "Display name of the agent." + "description": "智能体显示名称。", + "maxLength": 128 }, "description": { "type": "string", - "description": "What this agent does and when to delegate to it." + "description": "智能体描述。" }, "card_url": { "type": "string", - "description": "URL of the agent's published A2A agent card." + "description": "远程智能体卡片的 URL。" }, "auth_type": { "type": "string", - "description": "Authentication scheme used when calling the agent." + "description": "远程智能体的认证类型。" }, "auth_config": { "type": "object", "additionalProperties": { "type": "string" }, - "description": "Authentication parameters keyed by name." + "description": "认证配置键值对。" }, "streaming": { "type": "boolean", - "description": "Whether the agent supports streaming responses." + "description": "远程智能体是否支持流式响应。" }, "team_id": { "type": "integer", - "format": "int64", - "description": "Owning team for the new agent; 0 for account scope." + "description": "团队范围：0 表示账户级；>0 表示团队。", + "format": "int64" }, "auth_mode": { "type": "string", - "description": "Credential model; defaults to shared." + "description": "认证模式：shared（默认）、per_user_secret 或 per_user_oauth。" }, "secret_schema": { "type": "string", - "description": "JSON schema of the per-user secret; required when auth_mode is per_user_secret." + "description": "JSON 密钥 schema；auth_mode=per_user_secret 时必填。" }, "oauth_metadata": { "type": "string", - "description": "OAuth metadata JSON; reserved for OAuth-based auth." + "description": "JSON OAuth 元数据；为 per_user_oauth 预留。" } }, "required": [ @@ -40588,15 +40654,17 @@ }, "MCPServerListRequest": { "type": "object", - "description": "Filters for listing MCP servers.", + "description": "MCP 服务器列表的分页与团队过滤条件。", "properties": { "p": { "type": "integer", - "description": "Page number, starting at 1." + "description": "页码，从 1 开始。", + "default": 1 }, "limit": { "type": "integer", - "description": "Page size; defaults to 20." + "description": "每页数量。", + "default": 20 }, "team_ids": { "type": "array", @@ -40604,21 +40672,24 @@ "type": "integer", "format": "int64" }, - "description": "Restrict results to resources owned by these teams; intersected with the caller's visible set." + "description": "按团队 ID 过滤；为空则使用调用者可见范围。" }, "include_account": { - "type": "boolean", - "description": "Include account-scoped rows alongside team-scoped ones; defaults to true." + "type": [ + "boolean", + "null" + ], + "description": "是否包含账户级（team_id=0）记录，默认 true。" } } }, "A2AAgentCreateResponse": { "type": "object", - "description": "Identifier of the newly created A2A agent.", + "description": "注册 A2A 智能体的结果。", "properties": { "agent_id": { "type": "string", - "description": "Identifier of the created agent." + "description": "新建智能体的 ID。" } }, "required": [ @@ -40761,11 +40832,11 @@ }, "A2AAgentIDRequest": { "type": "object", - "description": "Selector for a single A2A agent.", + "description": "按 ID 查询 A2A 智能体。", "properties": { "agent_id": { "type": "string", - "description": "Identifier of the target agent." + "description": "目标智能体 ID。" } }, "required": [ @@ -40935,33 +41006,37 @@ }, "SessionListRequest": { "type": "object", - "description": "Filters for listing agent sessions. Reads are scoped to the account the app_key resolves to and to the resolved person's visible teams.", + "description": "查询智能体会话列表的过滤条件。读取范围限定为解析出的账户及调用者可见的团队。", "properties": { "app_name": { "type": "string", - "description": "Agent app whose sessions to list.", + "description": "要查询其会话的智能体应用。", "enum": [ "ask-ai", "support", "support-website", "support-flashcat", "ai-sre", - "template-assistant" + "template-assistant", + "swe" ] }, "p": { "type": "integer", - "description": "1-based page number; defaults to 1." + "description": "页码，从 1 开始。", + "default": 1, + "minimum": 1 }, "limit": { "type": "integer", - "description": "Page size, 1..100; defaults to 20.", + "description": "每页数量，1–100。", "minimum": 1, - "maximum": 100 + "maximum": 100, + "default": 20 }, "orderby": { "type": "string", - "description": "Sort column.", + "description": "排序字段。", "enum": [ "created_at", "updated_at" @@ -40969,20 +41044,20 @@ }, "asc": { "type": "boolean", - "description": "Ascending sort when true; defaults to false (descending). Only honored when orderby is set." + "description": "为 true 时升序；仅在设置 `orderby` 时生效。" }, "include_subagent_sessions": { "type": "boolean", - "description": "Include subagent (child) sessions in the result; defaults to false." + "description": "是否在列表中包含子智能体派生的会话。" }, "keyword": { "type": "string", - "maxLength": 64, - "description": "Case-insensitive substring match against session name." + "description": "按会话名称关键字过滤。", + "maxLength": 64 }, "scope": { "type": "string", - "description": "Visibility scope: all (own + member-of-team rows, the default), personal (own only), or team (member teams only).", + "description": "可见范围：all（本人 + 所属团队，默认）、personal 或 team。", "enum": [ "all", "personal", @@ -40995,7 +41070,7 @@ "type": "integer", "format": "int64" }, - "description": "Optional explicit team filter; intersected with the caller's visible set / scope." + "description": "可选的团队过滤；与 `scope` 取交集。" }, "entry_kinds": { "type": "array", @@ -41005,14 +41080,14 @@ "web", "im", "api", - "scheduled" + "automation" ] }, - "description": "Restrict to sessions produced by these entry surfaces. Empty returns every kind." + "description": "仅返回由这些入口产生的会话；为空则返回所有类型。" }, "status": { "type": "string", - "description": "Archive bucket: active (default, not archived), archived, or all.", + "description": "归档分桶：active（默认）返回未归档，archived 返回已归档，all 返回全部。", "enum": [ "active", "archived", @@ -41026,105 +41101,105 @@ }, "SessionTokenUsage": { "type": "object", - "description": "Cumulative session-level token rollup across all turns. The account-billing source of truth.", + "description": "跨所有轮次的会话级 token 累计汇总。账户计费的权威来源。", "properties": { "input_tokens": { "type": "integer", "format": "int64", - "description": "Total prompt (input) tokens, including the cached portion." + "description": "提示（输入）token 总数，含缓存部分。" }, "cached_tokens": { "type": "integer", "format": "int64", - "description": "Portion of input_tokens served from the prompt cache." + "description": "input_tokens 中由提示缓存命中的部分。" }, "output_tokens": { "type": "integer", "format": "int64", - "description": "Total generated (output) tokens." + "description": "生成（输出）token 总数。" }, "reasoning_tokens": { "type": "integer", "format": "int64", - "description": "Total reasoning/thinking tokens." + "description": "推理/思考 token 总数。" } } }, "EnvironmentBinding": { "type": "object", - "description": "The runner or cloud sandbox the session is bound to. Null until the first message.", + "description": "会话绑定的 runner 或云沙箱。首条消息前为 null。", "properties": { "kind": { "type": "string", - "description": "Environment kind (e.g. runner, sandbox)." + "description": "环境类型（如 runner、sandbox）。" }, "id": { "type": "string", - "description": "Environment identifier." + "description": "环境标识。" }, "name": { "type": "string", - "description": "Human-readable environment name." + "description": "可读的环境名称。" }, "status": { "type": "string", - "description": "Binding status." + "description": "绑定状态。" } } }, "ContextResolvedItem": { "type": "object", - "description": "Snapshot of the three-tier knowledge-pack resolution for this session.", + "description": "该会话三层知识包解析结果的快照。", "properties": { "account_pack_id": { "type": "string", - "description": "Resolved account-scoped pack id." + "description": "解析出的账户级知识包 ID。" }, "team_pack_id": { "type": "string", - "description": "Resolved team-scoped pack id." + "description": "解析出的团队级知识包 ID。" }, "incident_id": { "type": "string", - "description": "Bound incident id, when war-room originated." + "description": "作战室来源时绑定的故障 ID。" }, "resolved_at_ms": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds when the packs were resolved." + "description": "知识包解析时间，Unix 毫秒时间戳。" }, "versions": { "type": "object", "additionalProperties": { "type": "integer" }, - "description": "Per-pack resolved version map." + "description": "各知识包解析版本映射。" } } }, "SessionItem": { "type": "object", - "description": "One agent session row.", + "description": "单条智能体会话记录。", "properties": { "session_id": { "type": "string", - "description": "Session identifier." + "description": "会话标识。" }, "parent_session_id": { "type": "string", - "description": "Parent session id for subagent (child) sessions; empty otherwise." + "description": "子智能体（子）会话的父会话 ID；否则为空。" }, "session_name": { "type": "string", - "description": "Session title; may be empty for untitled sessions." + "description": "会话标题；未命名会话可能为空。" }, "app_name": { "type": "string", - "description": "Agent app that owns the session." + "description": "拥有该会话的智能体应用。" }, "entry_kind": { "type": "string", - "description": "Surface that created the session.", + "description": "创建该会话的入口来源。", "enum": [ "web", "im", @@ -41135,28 +41210,28 @@ }, "person_id": { "type": "string", - "description": "Creator person id." + "description": "创建者人员 ID。" }, "team_id": { "type": "integer", "format": "int64", - "description": "Owning team id; 0 means no team is bound. Immutable after create." + "description": "所属团队 ID；0 表示未绑定团队。创建后不可变更。" }, "team_name": { "type": "string", - "description": "Resolved team name; empty for unbound rows or deleted teams." + "description": "解析出的团队名称；未绑定或团队已删除时为空。" }, "is_mine": { "type": "boolean", - "description": "True when the caller created this session." + "description": "当该会话由调用者创建时为 true。" }, "can_manage": { "type": "boolean", - "description": "True when the caller may rename/archive/delete the session." + "description": "当调用者可重命名/归档/删除该会话时为 true。" }, "status": { "type": "string", - "description": "Lifecycle status.", + "description": "生命周期状态。", "enum": [ "enabled", "deleted" @@ -41164,26 +41239,26 @@ }, "incognito": { "type": "boolean", - "description": "True for incognito (non-persisted-memory) sessions." + "description": "无痕（不持久化记忆）会话时为 true。" }, "created_at": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds when the session was created." + "description": "会话创建时间，Unix 毫秒时间戳。" }, "updated_at": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds of the last session update." + "description": "会话最近更新时间，Unix 毫秒时间戳。" }, "template_staging_round_id": { "type": "string", - "description": "Current save→validate round id (template-assistant only); empty otherwise." + "description": "当前 save→validate 轮次 ID（仅 template-assistant）；否则为空。" }, "state": { "type": "object", "additionalProperties": true, - "description": "Raw session-state bag (session-scoped keys). Omitted when empty." + "description": "原始会话状态包（会话级键）。为空时省略。" }, "bound_environment": { "$ref": "#/components/schemas/EnvironmentBinding" @@ -41197,81 +41272,81 @@ "current_context_tokens": { "type": "integer", "format": "int64", - "description": "Size in tokens of the LLM context window as of the most recent turn. 0 means no turn has completed." + "description": "截至最近一轮的 LLM 上下文窗口的 token 数。0 表示尚无已完成的轮次。" }, "context_window": { "type": "integer", "format": "int64", - "description": "The bound model's max context size in tokens. 0 means unknown." + "description": "所绑定模型的最大上下文 token 数。0 表示未知。" }, "archived_at": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds when archived; 0 means not archived." + "description": "归档时间，Unix 毫秒时间戳；0 表示未归档。" }, "pinned_at": { "type": "integer", "format": "int64", - "description": "Caller's per-user pin timestamp in milliseconds; 0 means not pinned." + "description": "调用者的个人置顶时间，Unix 毫秒时间戳；0 表示未置顶。" }, "last_event_at": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds of the most recent assistant-side event." + "description": "最近一条助手侧事件的时间，Unix 毫秒时间戳。" }, "is_running": { "type": "boolean", - "description": "True when an agent turn is currently in flight for this session." + "description": "当该会话当前有正在进行的智能体轮次时为 true。" }, "has_unread": { "type": "boolean", - "description": "True when there is assistant output the caller has not yet viewed." + "description": "当存在调用者尚未查看的助手输出时为 true。" } } }, "SessionListResponse": { "type": "object", - "description": "A page of agent sessions.", + "description": "一页智能体会话。", "properties": { "total": { "type": "integer", "format": "int64", - "description": "Total number of sessions matching the filter (ignoring pagination)." + "description": "匹配过滤条件的会话总数（忽略分页）。" }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionItem" }, - "description": "The page of sessions." + "description": "当前页的会话。" } } }, "SessionGetRequest": { "type": "object", - "description": "Fetch one session plus a recent page of its events.", + "description": "查询单个会话，并返回其最近事件的一页（向更早方向分页）。", "properties": { "session_id": { "type": "string", - "minLength": 1, - "description": "Session identifier." + "description": "目标会话 ID。", + "minLength": 1 }, "num_recent_events": { "type": "integer", + "description": "旧版每页数量：返回的最近事件数。与 `limit` 同时设置时以 `limit` 为准；0 使用服务端默认值（100）。", "minimum": 0, - "maximum": 1000, - "description": "Number of most-recent events to return; 0 uses the server default." + "maximum": 1000 }, "limit": { "type": "integer", + "description": "事件每页数量；优先于 `num_recent_events`。0 使用服务端默认值（100）。", "minimum": 0, - "maximum": 1000, - "description": "Alias for num_recent_events; takes precedence when both are set." + "maximum": 1000 }, "search_after_ctx": { "type": "string", - "maxLength": 4096, - "description": "Opaque keyset cursor from a previous response's search_after_ctx, to page backward through older events." + "description": "上一次响应返回的不透明游标；回传以获取更早的一页。", + "maxLength": 4096 } }, "required": [ @@ -41280,62 +41355,62 @@ }, "EventItem": { "type": "object", - "description": "One persisted session event. content/actions/usage_metadata carry the raw ADK envelope; treat them as opaque structured payloads.", + "description": "单条已持久化的会话事件。content/actions/usage_metadata 携带原始 ADK 信封，请将其视为不透明的结构化负载。", "properties": { "event_id": { "type": "string", - "description": "Event identifier." + "description": "事件标识。" }, "session_id": { "type": "string", - "description": "Owning session id." + "description": "所属会话 ID。" }, "invocation_id": { "type": "string", - "description": "ADK invocation id grouping a turn." + "description": "标识一轮的 ADK 调用 ID。" }, "author": { "type": "string", - "description": "Event author (e.g. user, the agent name)." + "description": "事件作者（如 user 或智能体名称）。" }, "branch": { "type": "string", - "description": "ADK branch path for nested agents." + "description": "嵌套智能体的 ADK 分支路径。" }, "content": { "type": "object", "additionalProperties": true, - "description": "ADK content envelope {role, parts:[...]}." + "description": "ADK content 信封 {role, parts:[...]}。" }, "actions": { "type": "object", "additionalProperties": true, - "description": "ADK actions envelope (state deltas, transfers, escalation)." + "description": "ADK actions 信封（状态增量、转移、升级）。" }, "usage_metadata": { "type": "object", "additionalProperties": true, - "description": "Per-turn token usage metadata." + "description": "单轮 token 用量元数据。" }, "partial": { "type": "boolean", - "description": "True for a streaming partial chunk." + "description": "流式部分分片时为 true。" }, "turn_complete": { "type": "boolean", - "description": "True on the terminal event of a turn." + "description": "一轮的终止事件上为 true。" }, "error_code": { "type": "string", - "description": "Error code when the event represents a failure." + "description": "当该事件表示失败时的错误码。" }, "error_message": { "type": "string", - "description": "Human-readable error message, when present." + "description": "可读的错误信息（如有）。" }, "status": { "type": "string", - "description": "Event status.", + "description": "事件状态。", "enum": [ "normal", "compressed" @@ -41344,13 +41419,13 @@ "created_at": { "type": "integer", "format": "int64", - "description": "Unix timestamp in milliseconds when the event was written." + "description": "事件写入时间，Unix 毫秒时间戳。" } } }, "SessionGetResponse": { "type": "object", - "description": "A session plus a backward-paged window of its events.", + "description": "一个会话及其事件的一页（向更早方向分页）。", "properties": { "session": { "$ref": "#/components/schemas/SessionItem" @@ -41360,165 +41435,75 @@ "items": { "$ref": "#/components/schemas/EventItem" }, - "description": "Recent events, ascending by (created_at, event_id)." + "description": "最近事件，按 (created_at, event_id) 升序排列。" }, "has_more_older": { "type": "boolean", - "description": "True when older events remain beyond this page." + "description": "当本页之外仍有更早的事件时为 true。" }, "search_after_ctx": { "type": "string", - "description": "Opaque keyset cursor; pass back as search_after_ctx to fetch the next older page. Omitted when has_more_older is false." + "description": "不透明游标；作为 search_after_ctx 回传以获取更早的一页。has_more_older 为 false 时省略。" } } }, "SessionExportRequest": { "type": "object", - "description": "Export the full event transcript of one session as a streaming NDJSON body.", + "description": "以流式 NDJSON 导出单个会话的完整事件记录。", "properties": { "session_id": { "type": "string", - "description": "Session identifier to export." + "description": "目标会话 ID。" }, "include_subagents": { "type": "boolean", - "description": "When true, each subagent_dispatch line is followed by the child session's full event stream, bracketed by its own session_meta. Defaults to false." + "description": "为 true 时，每条 subagent_dispatch 行后会跟随子会话的完整事件流，并以其自身的 session_meta 包裹。默认 false。" } }, "required": [ "session_id" ] }, - "ExportUsage": { + "SkillUploadRequest": { "type": "object", - "description": "Per-LLM-call token counts on an export line. Absent fields are 0.", + "description": "上传技能压缩包的 multipart 表单。", "properties": { - "input_tokens": { - "type": "integer", - "description": "Prompt (input) tokens for the call." + "file": { + "type": "string", + "format": "binary", + "description": "技能压缩包（.skill / .zip / .tar.gz / .tgz），最大 100MB。" }, - "output_tokens": { + "team_id": { "type": "integer", - "description": "Generated (output) tokens for the call." + "description": "新技能的团队范围：0 表示账户级。", + "format": "int64" }, - "cache_read": { - "type": "integer", - "description": "Tokens served from the prompt cache." + "replace": { + "type": "boolean", + "description": "为 true 时覆盖同名技能。" }, - "cache_creation": { - "type": "integer", - "description": "Tokens written to the prompt cache." + "skill_id": { + "type": "string", + "description": "替换指定技能时的技能 ID。" } - } + }, + "required": [ + "file" + ] }, - "ExportLine": { + "SessionDeleteRequest": { "type": "object", - "description": "One line of the NDJSON export stream. The `type` field discriminates the line: session_meta (always first), user_message, llm_call, tool_call, subagent_dispatch, final_answer, agent_text, or error (emitted only if the stream is truncated mid-export). Fields are sparse — only those relevant to the line type are present.", + "description": "按 ID 删除会话。", "properties": { - "type": { - "type": "string", - "description": "Line discriminator.", - "enum": [ - "session_meta", - "user_message", - "llm_call", - "tool_call", - "subagent_dispatch", - "final_answer", - "agent_text", - "error" - ] - }, - "seq": { - "type": "integer", - "description": "1-based monotonic sequence within the session (absent on session_meta)." - }, "session_id": { "type": "string", - "description": "Session id (on session_meta)." - }, - "account_id": { - "type": "integer", - "format": "int64", - "description": "Account id (on session_meta)." - }, - "app_name": { - "type": "string", - "description": "Agent app (on session_meta)." - }, - "parent_session_id": { - "type": "string", - "description": "Parent session id for child sessions (on session_meta)." - }, - "started_at": { - "type": "string", - "format": "date-time", - "description": "RFC3339 start timestamp (session_meta uses session.created_at)." - }, - "ended_at": { - "type": "string", - "format": "date-time", - "description": "RFC3339 end timestamp; stamped on llm_call/tool_call/session_meta." - }, - "model": { - "type": "string", - "description": "Chat model provider key; on session_meta and llm_call." - }, - "content": { - "type": "string", - "description": "Text content of the line (messages, answers, errors)." - }, - "ts": { - "type": "string", - "format": "date-time", - "description": "RFC3339 timestamp of the event." - }, - "usage": { - "$ref": "#/components/schemas/ExportUsage" - }, - "name": { - "type": "string", - "description": "Tool name (on tool_call)." - }, - "input": { - "type": "object", - "additionalProperties": true, - "description": "Tool call input arguments (on tool_call)." - }, - "output": { - "type": "string", - "description": "Tool call output (on tool_call response side)." - }, - "status": { - "type": "string", - "description": "Tool result status, e.g. ok or error." - }, - "duration_ms": { - "type": "integer", - "format": "int64", - "description": "Call duration in milliseconds." - }, - "input_bytes": { - "type": "integer", - "description": "Byte size of the tool input." - }, - "output_bytes": { - "type": "integer", - "description": "Byte size of the tool output." - }, - "error": { - "type": "string", - "description": "Error detail when a call failed." - }, - "agent_name": { - "type": "string", - "description": "Dispatched subagent name (on subagent_dispatch)." - }, - "child_session_id": { - "type": "string", - "description": "Child session id created by the dispatch (on subagent_dispatch)." + "description": "目标会话 ID。", + "minLength": 1 } - } + }, + "required": [ + "session_id" + ] } } } diff --git a/roundtrip_gen_test.go b/roundtrip_gen_test.go index 3c05941..0310226 100644 --- a/roundtrip_gen_test.go +++ b/roundtrip_gen_test.go @@ -147,11 +147,11 @@ var exampleDataDecoders = map[string]func(json.RawMessage) error{ "POST /safari/mcp/server/get": func(d json.RawMessage) error { var v McpServerItem; return json.Unmarshal(d, &v) }, "POST /safari/mcp/server/list": func(d json.RawMessage) error { var v McpServerListResponse; return json.Unmarshal(d, &v) }, "POST /safari/mcp/server/update": func(d json.RawMessage) error { var v McpServerItem; return json.Unmarshal(d, &v) }, + "POST /safari/session/delete": func(d json.RawMessage) error { var v any; return json.Unmarshal(d, &v) }, "POST /safari/session/get": func(d json.RawMessage) error { var v SessionGetResponse; return json.Unmarshal(d, &v) }, "POST /safari/session/list": func(d json.RawMessage) error { var v SessionListResponse; return json.Unmarshal(d, &v) }, "POST /safari/skill/delete": func(d json.RawMessage) error { var v any; return json.Unmarshal(d, &v) }, "POST /safari/skill/disable": func(d json.RawMessage) error { var v any; return json.Unmarshal(d, &v) }, - "POST /safari/skill/download": func(d json.RawMessage) error { var v string; return json.Unmarshal(d, &v) }, "POST /safari/skill/enable": func(d json.RawMessage) error { var v any; return json.Unmarshal(d, &v) }, "POST /safari/skill/get": func(d json.RawMessage) error { var v SkillItem; return json.Unmarshal(d, &v) }, "POST /safari/skill/list": func(d json.RawMessage) error { var v SkillListResponse; return json.Unmarshal(d, &v) }, diff --git a/sessions.go b/sessions.go index f2d2c89..50c1aed 100644 --- a/sessions.go +++ b/sessions.go @@ -9,10 +9,10 @@ type SessionsService service // Get session detail. // -// Fetch one session plus a backward-paged window of its most recent events. Use search_after_ctx to page through older history. +// Fetch one session plus a backward-paged window of its most recent events. // // API: POST /safari/session/get (session-read-info). -func (s *SessionsService) Info(ctx context.Context, req *SessionGetRequest) (*SessionGetResponse, *Response, error) { +func (s *SessionsService) ReadInfo(ctx context.Context, req *SessionGetRequest) (*SessionGetResponse, *Response, error) { out := new(SessionGetResponse) resp, err := s.client.do(ctx, "/safari/session/get", req, out) if err != nil { @@ -23,10 +23,10 @@ func (s *SessionsService) Info(ctx context.Context, req *SessionGetRequest) (*Se // List sessions. // -// List agent sessions visible to the caller within the resolved account, filtered by app, entry surface, archive status, and team scope, with pagination. Reads are scoped to the person the app_key resolves to. +// List agent sessions visible to the caller, filtered by app, surface, archive status, and team. // // API: POST /safari/session/list (session-read-list). -func (s *SessionsService) List(ctx context.Context, req *SessionListRequest) (*SessionListResponse, *Response, error) { +func (s *SessionsService) ReadList(ctx context.Context, req *SessionListRequest) (*SessionListResponse, *Response, error) { out := new(SessionListResponse) resp, err := s.client.do(ctx, "/safari/session/list", req, out) if err != nil { @@ -34,3 +34,17 @@ func (s *SessionsService) List(ctx context.Context, req *SessionListRequest) (*S } return out, resp, nil } + +// Delete session. +// +// Delete a session by ID. +// +// API: POST /safari/session/delete (session-write-delete). +func (s *SessionsService) WriteDelete(ctx context.Context, req *SessionDeleteRequest) (*any, *Response, error) { + out := new(any) + resp, err := s.client.do(ctx, "/safari/session/delete", req, out) + if err != nil { + return nil, resp, err + } + return out, resp, nil +} diff --git a/sessions_export.go b/sessions_export.go index d87ff80..c3b8bd7 100644 --- a/sessions_export.go +++ b/sessions_export.go @@ -97,3 +97,68 @@ func DecodeExportLine(line []byte) (*ExportLine, error) { } return &l, nil } + +// ExportLine is one decoded line of a session export stream. The Type field +// discriminates the event kind (session_meta, user_message, llm_call, tool_call, +// subagent_dispatch, final_answer, agent_text, error); the remaining fields are +// populated per kind. It is hand-maintained here, alongside the hand-written +// streaming Export endpoint, because the typed generator only models JSON-envelope +// responses and excludes the NDJSON export stream (so its line schema is pruned as +// unreferenced). +type ExportLine struct { + // Account id (on session_meta). + AccountID int64 `json:"account_id" toon:"account_id"` + // Dispatched subagent name (on subagent_dispatch). + AgentName string `json:"agent_name" toon:"agent_name"` + // Agent app (on session_meta). + AppName string `json:"app_name" toon:"app_name"` + // Child session id created by the dispatch (on subagent_dispatch). + ChildSessionID string `json:"child_session_id" toon:"child_session_id"` + // Text content of the line (messages, answers, errors). + Content string `json:"content" toon:"content"` + // Call duration in milliseconds. + DurationMs int64 `json:"duration_ms" toon:"duration_ms"` + // RFC3339 end timestamp; stamped on llm_call/tool_call/session_meta. + EndedAt string `json:"ended_at" toon:"ended_at"` + // Error detail when a call failed. + Error string `json:"error" toon:"error"` + // Tool call input arguments (on tool_call). + Input map[string]any `json:"input" toon:"input"` + // Byte size of the tool input. + InputBytes int64 `json:"input_bytes" toon:"input_bytes"` + // Chat model provider key; on session_meta and llm_call. + Model string `json:"model" toon:"model"` + // Tool name (on tool_call). + Name string `json:"name" toon:"name"` + // Tool call output (on tool_call response side). + Output string `json:"output" toon:"output"` + // Byte size of the tool output. + OutputBytes int64 `json:"output_bytes" toon:"output_bytes"` + // Parent session id for child sessions (on session_meta). + ParentSessionID string `json:"parent_session_id" toon:"parent_session_id"` + // 1-based monotonic sequence within the session (absent on session_meta). + Seq int64 `json:"seq" toon:"seq"` + // Session id (on session_meta). + SessionID string `json:"session_id" toon:"session_id"` + // RFC3339 start timestamp (session_meta uses session.created_at). + StartedAt string `json:"started_at" toon:"started_at"` + // Tool result status, e.g. ok or error. + Status string `json:"status" toon:"status"` + // RFC3339 timestamp of the event. + TS string `json:"ts" toon:"ts"` + // Line discriminator. + Type string `json:"type" toon:"type"` + Usage ExportUsage `json:"usage" toon:"usage"` +} + +// ExportUsage is the token-usage sub-object on an ExportLine (llm_call events). +type ExportUsage struct { + // Tokens written to the prompt cache. + CacheCreation int64 `json:"cache_creation" toon:"cache_creation"` + // Tokens served from the prompt cache. + CacheRead int64 `json:"cache_read" toon:"cache_read"` + // Prompt (input) tokens for the call. + InputTokens int64 `json:"input_tokens" toon:"input_tokens"` + // Generated (output) tokens for the call. + OutputTokens int64 `json:"output_tokens" toon:"output_tokens"` +} diff --git a/skills.go b/skills.go index 989de76..f4fa2a6 100644 --- a/skills.go +++ b/skills.go @@ -7,23 +7,9 @@ import "context" // SkillsService handles the "AI SRE/Skills" API resource. type SkillsService service -// Download skill. -// -// Download the original zip package of a skill as a binary attachment. -// -// API: POST /safari/skill/download (skill-read-download). -func (s *SkillsService) ReadDownload(ctx context.Context, req *SkillDownloadRequest) (*string, *Response, error) { - out := new(string) - resp, err := s.client.do(ctx, "/safari/skill/download", req, out) - if err != nil { - return nil, resp, err - } - return out, resp, nil -} - // Enable skill. // -// Activate a disabled skill so agents can load it at session start. +// Enable a disabled skill so the agent can load it. // // API: POST /safari/skill/enable (skill-read-enable). func (s *SkillsService) ReadEnable(ctx context.Context, req *SkillStatusRequest) (*any, *Response, error) { @@ -37,7 +23,7 @@ func (s *SkillsService) ReadEnable(ctx context.Context, req *SkillStatusRequest) // Get skill detail. // -// Return the full configuration and SKILL.md body of a single skill by ID. +// Get one skill including its full SKILL.md content. // // API: POST /safari/skill/get (skill-read-get). func (s *SkillsService) ReadGet(ctx context.Context, req *SkillGetRequest) (*SkillItem, *Response, error) { @@ -65,7 +51,7 @@ func (s *SkillsService) ReadList(ctx context.Context, req *SkillListRequest) (*S // Delete skill. // -// Permanently remove a skill so agents can no longer load it. +// Delete a skill by ID. // // API: POST /safari/skill/delete (skill-write-delete). func (s *SkillsService) WriteDelete(ctx context.Context, req *SkillDeleteRequest) (*any, *Response, error) { @@ -79,7 +65,7 @@ func (s *SkillsService) WriteDelete(ctx context.Context, req *SkillDeleteRequest // Disable skill. // -// Deactivate an enabled skill so agents no longer load it. +// Disable an enabled skill so the agent stops loading it. // // API: POST /safari/skill/disable (skill-write-disable). func (s *SkillsService) WriteDisable(ctx context.Context, req *SkillStatusRequest) (*any, *Response, error) { @@ -93,7 +79,7 @@ func (s *SkillsService) WriteDisable(ctx context.Context, req *SkillStatusReques // Update skill. // -// Edit a skill's description or reassign its owning team. +// Update a skill's description or reassign its team scope. // // API: POST /safari/skill/update (skill-write-update). func (s *SkillsService) WriteUpdate(ctx context.Context, req *SkillUpdateRequest) (*SkillItem, *Response, error) { @@ -107,7 +93,7 @@ func (s *SkillsService) WriteUpdate(ctx context.Context, req *SkillUpdateRequest // Upload skill. // -// Upload a skill zip package and register it as a new account or team skill. +// Upload a skill archive (.skill/.zip/.tar.gz/.tgz) to create or replace a skill. // // API: POST /safari/skill/upload (skill-write-upload). func (s *SkillsService) WriteUpload(ctx context.Context) (*SkillItem, *Response, error) {