{ "components": { "parameters": {}, "schemas": { "ActionRequiredEvent": { "discriminator": { "mapping": { "mcp.auth_required": "#/components/schemas/MCPAuthRequiredEvent", "tool.approval_required": "#/components/schemas/ToolApprovalRequiredEvent", "tool.response_required": "#/components/schemas/ToolResponseRequiredEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ToolApprovalRequiredEvent" }, { "$ref": "#/components/schemas/ToolResponseRequiredEvent" }, { "$ref": "#/components/schemas/MCPAuthRequiredEvent" } ] }, "Agent": { "additionalProperties": false, "properties": { "created_by_subject": { "$ref": "#/components/schemas/Subject" }, "description": { "maxLength": 1024, "minLength": 1, "type": "string" }, "id": { "description": "Immutable server-generated agent identifier.", "minLength": 1, "type": "string" }, "manifest": { "$ref": "#/components/schemas/AgentSpec" }, "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "id", "name", "description", "manifest", "created_by_subject" ], "type": "object" }, "AgentCodeSnippet": { "additionalProperties": false, "properties": { "icon": { "format": "uri", "type": "string" }, "label_name": { "minLength": 1, "type": "string" }, "language": { "minLength": 1, "type": "string" }, "sample_code": { "$ref": "#/components/schemas/AgentCodeSnippetSampleCode" } }, "required": [ "label_name", "language", "icon", "sample_code" ], "type": "object" }, "AgentCodeSnippetSampleCode": { "additionalProperties": false, "properties": { "non_stream": { "description": "SDK sample that creates a turn without streaming.", "type": "string" }, "stream": { "description": "SDK sample that streams turn events.", "type": "string" } }, "required": [ "stream", "non_stream" ], "type": "object" }, "AgentCodeSnippets": { "additionalProperties": false, "properties": { "base_url": { "description": "Public base URL for the TrueForge SDK `baseUrl`.", "format": "uri", "type": "string" }, "snippets": { "items": { "$ref": "#/components/schemas/AgentCodeSnippet" }, "type": "array" } }, "required": [ "base_url", "snippets" ], "type": "object" }, "AgentInfo": { "properties": { "input": { "description": "Input prompt passed to the subagent.", "type": "string" }, "model": { "description": "Optional model override for the subagent.", "minLength": 1, "type": "string" }, "name": { "description": "Display name of the dynamic subagent.", "type": "string" }, "type": { "description": "Subagent kind.", "enum": [ "dynamic" ], "type": "string" } }, "required": [ "type", "name", "input" ], "type": "object" }, "AgentParent": { "properties": { "thread_id": { "description": "Parent thread that spawned the child agent.", "type": "string" }, "tool_call_id": { "description": "Tool call on the parent thread that created the child.", "type": "string" } }, "required": [ "thread_id", "tool_call_id" ], "type": "object" }, "AgentSpec": { "description": "Complete agent definition used inline on a session or saved as a named agent.", "properties": { "config": { "$ref": "#/components/schemas/RuntimeConfig" }, "instructions": { "description": "Optional system prompt — the agent's role, behavior, and constraints.", "type": "string" }, "mcp_servers": { "description": "Optional MCP servers attached by configured name.", "items": { "$ref": "#/components/schemas/MCPServer" }, "type": "array" }, "messages": { "description": "Optional initial user messages injected at the start of every session.", "items": { "$ref": "#/components/schemas/InitialUserMessage" }, "type": "array" }, "model": { "$ref": "#/components/schemas/Model" }, "response_format": { "$ref": "#/components/schemas/ResponseFormat" }, "skills": { "description": "Skills used in this agent.", "items": { "$ref": "#/components/schemas/Skill" }, "maxItems": 50, "type": "array" } }, "required": [ "model" ], "type": "object" }, "AlibabaModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "default": "https://dashscope-intl.aliyuncs.com/compatible-mode/v1", "description": "Override of the provider's default API base URL.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "alibaba" ], "type": "string" } }, "required": [ "auth", "models", "type" ], "type": "object" }, "AnthropicModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "default": "https://api.anthropic.com/v1", "description": "Override of the provider's default API base URL.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "anthropic" ], "type": "string" } }, "required": [ "auth", "models", "type" ], "type": "object" }, "ApprovalAllow": { "properties": { "status": { "description": "Allow the pending tool call(s).", "enum": [ "allow" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "ApprovalDecision": { "discriminator": { "mapping": { "allow": "#/components/schemas/ApprovalAllow", "deny": "#/components/schemas/ApprovalDeny" }, "propertyName": "status" }, "oneOf": [ { "$ref": "#/components/schemas/ApprovalAllow" }, { "$ref": "#/components/schemas/ApprovalDeny" } ] }, "ApprovalDeny": { "properties": { "reason": { "description": "Optional reason shown to the agent when denied.", "type": "string" }, "status": { "description": "Deny the pending tool call(s).", "enum": [ "deny" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "AskUserQuestionsConfig": { "default": { "enabled": true }, "properties": { "enabled": { "default": true, "description": "Enable the `ask_user_question` tool. Default: true.", "type": "boolean" } }, "type": "object" }, "AvailableMCPServer": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/MCPServerAuthPublic" }, "auth_status": { "$ref": "#/components/schemas/MCPAuthStatus" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "url": { "description": "URL of the remote MCP server.", "format": "uri", "type": "string" } }, "required": [ "name", "url", "auth_status" ], "type": "object" }, "AvailableModel": { "additionalProperties": false, "properties": { "model_id": { "description": "Upstream, provider-specific identifier sent to the provider API.", "type": "string" }, "name": { "description": "Fully qualified name `provider_name/model_name`, e.g. \"openai/gpt-5-6-sol\". Unique within a tenant.", "type": "string" }, "properties": { "$ref": "#/components/schemas/ModelProperties" }, "provider": { "$ref": "#/components/schemas/AvailableModelProvider" }, "warning": { "description": "Set when reasoning effort or context length is not configured; may affect TrueForge performance.", "minLength": 1, "type": "string" } }, "required": [ "name", "model_id", "provider", "properties" ], "type": "object" }, "AvailableModelProvider": { "additionalProperties": false, "description": "Owning configured provider.", "properties": { "name": { "description": "Configured provider resource name; matches the FQN prefix of `name`.", "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "AvailableSkill": { "additionalProperties": false, "properties": { "description": { "description": "Concise guidance for when the agent should use the skill.", "minLength": 1, "type": "string" }, "metadata": { "additionalProperties": { "type": "string" }, "description": "Optional skill metadata.", "type": "object" }, "name": { "description": "Skill name.", "minLength": 1, "type": "string" } }, "required": [ "name", "description" ], "type": "object" }, "BaseMCPAuthRequiredEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "thread_id": { "description": "Always null — this is a run-level event.", "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "thread_id" ], "type": "object" }, "CancelSessionRequest": { "description": "Empty request body. Cancel identifies the session via the path only.", "properties": {}, "type": "object" }, "CancelSessionResponse": { "description": "Empty success body. HTTP 200 means the cancel request was accepted (or nothing was running).", "properties": {}, "type": "object" }, "CapabilitiesData": { "properties": { "memory": { "$ref": "#/components/schemas/MemoryCapability" }, "sandbox": { "$ref": "#/components/schemas/SandboxCapability" }, "session_sharing": { "$ref": "#/components/schemas/SessionSharingCapability" }, "settings": { "$ref": "#/components/schemas/SettingsCapability" }, "skill": { "$ref": "#/components/schemas/SkillCapability" }, "web_search": { "$ref": "#/components/schemas/WebSearchCapability" } }, "required": [ "sandbox", "skill", "settings", "web_search", "session_sharing" ], "type": "object" }, "CatalogCustomModelProvider": { "additionalProperties": false, "properties": { "supported_reasoning_efforts": { "description": "Supported reasoning-effort values for this provider", "items": { "$ref": "#/components/schemas/ReasoningEffort" }, "type": "array" }, "type": { "enum": [ "custom" ], "type": "string" } }, "required": [ "type", "supported_reasoning_efforts" ], "type": "object" }, "CatalogMCPServer": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/MCPServerManifestAuth" }, "description": { "description": "Concise summary of what this MCP server provides.", "minLength": 1, "type": "string" }, "logo": { "description": "URL of the MCP server logo asset.", "format": "uri", "type": "string" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "type": { "$ref": "#/components/schemas/CatalogMCPServerType" }, "url": { "description": "URL of the remote MCP server.", "format": "uri", "type": "string" } }, "required": [ "type", "name", "url", "description" ], "type": "object" }, "CatalogMCPServerType": { "enum": [ "remote" ], "type": "string" }, "CatalogMemoryProvider": { "additionalProperties": false, "properties": { "type": { "description": "Zep memory provider.", "enum": [ "zep" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "CatalogModel": { "additionalProperties": false, "properties": { "model_id": { "description": "Upstream, provider-specific identifier sent to the provider API.", "minLength": 1, "type": "string" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "properties": { "$ref": "#/components/schemas/ModelProperties" } }, "required": [ "model_id", "name", "properties" ], "type": "object" }, "CatalogModelProvider": { "anyOf": [ { "$ref": "#/components/schemas/CatalogWellKnownModelProvider" }, { "$ref": "#/components/schemas/CatalogCustomModelProvider" } ] }, "CatalogSandboxProvider": { "additionalProperties": false, "properties": { "auto_archive_interval_in_minutes": { "description": "Minutes before Daytona auto-archives the sandbox (0 disables).", "minimum": 0, "type": "integer" }, "auto_delete_interval_in_minutes": { "description": "Minutes before Daytona auto-deletes the sandbox (0 disables).", "minimum": 0, "type": "integer" }, "auto_stop_interval_in_minutes": { "description": "Minutes of idle time before Daytona auto-stops the sandbox (0 disables).", "minimum": 0, "type": "integer" }, "exec_timeout_ms": { "description": "Default sandbox command exec timeout in milliseconds.", "exclusiveMinimum": 0, "type": "integer" }, "type": { "description": "Daytona sandbox provider.", "enum": [ "daytona" ], "type": "string" } }, "required": [ "type", "exec_timeout_ms", "auto_stop_interval_in_minutes", "auto_archive_interval_in_minutes", "auto_delete_interval_in_minutes" ], "type": "object" }, "CatalogSkill": { "additionalProperties": false, "properties": { "description": { "description": "Concise guidance for when the agent should use the skill.", "minLength": 1, "type": "string" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "path": { "description": "Path to the skill directory within the repository. Omit to use the repository root.", "minLength": 1, "pattern": "^[A-Za-z0-9._\\-/]+$", "type": "string" }, "ref": { "description": "Git ref — branch name, tag, or commit SHA.", "minLength": 1, "pattern": "^[A-Za-z0-9._\\-/]+$", "type": "string" }, "type": { "$ref": "#/components/schemas/CatalogSkillType" }, "url": { "description": "Full HTTPS URL of a GitHub or GitLab repository.", "minLength": 1, "pattern": "^https:\\/\\/(github\\.com\\/[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+|gitlab\\.com\\/[A-Za-z0-9._-]+(?:\\/[A-Za-z0-9._-]+)+)(\\/|\\.git)?$", "type": "string" } }, "required": [ "type", "name", "url", "ref", "description" ], "type": "object" }, "CatalogSkillType": { "enum": [ "git" ], "type": "string" }, "CatalogWebSearchProvider": { "additionalProperties": false, "properties": { "type": { "description": "Parallel web-search provider.", "enum": [ "parallel" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "CatalogWellKnownModelProvider": { "additionalProperties": false, "properties": { "logo": { "description": "URL of the provider logo asset", "format": "uri", "type": "string" }, "models": { "description": "Preset models", "items": { "$ref": "#/components/schemas/CatalogModel" }, "type": "array" }, "type": { "$ref": "#/components/schemas/CatalogWellKnownModelProviderType" } }, "required": [ "type", "models" ], "type": "object" }, "CatalogWellKnownModelProviderType": { "enum": [ "openai", "anthropic", "google-gemini", "fireworks", "zai", "moonshot", "alibaba", "together" ], "type": "string" }, "ChatCompletionChunkDeltaToolCall": { "properties": { "function": { "properties": { "arguments": { "description": "Partial or complete JSON arguments string.", "type": "string" }, "name": { "description": "Partial or complete function name.", "type": "string" } }, "type": "object" }, "id": { "description": "Tool call id (may arrive across multiple deltas).", "type": "string" }, "index": { "description": "Index of this tool call in the streaming delta array.", "minimum": 0, "type": "integer" }, "type": { "description": "Tool call type when present on this delta.", "enum": [ "function" ], "type": "string" } }, "required": [ "index" ], "type": "object" }, "ChatCompletionContentPartRefusal": { "properties": { "refusal": { "description": "Refusal message text.", "type": "string" }, "type": { "description": "Model refusal content part.", "enum": [ "refusal" ], "type": "string" } }, "required": [ "type", "refusal" ], "type": "object" }, "ChatCompletionContentPartText": { "properties": { "text": { "description": "Plain-text content.", "type": "string" }, "type": { "description": "Text content part.", "enum": [ "text" ], "type": "string" } }, "required": [ "type", "text" ], "type": "object" }, "ChatCompletionMessageToolCall": { "properties": { "function": { "properties": { "arguments": { "description": "JSON-encoded function arguments string.", "type": "string" }, "name": { "description": "Function/tool name.", "type": "string" } }, "required": [ "name", "arguments" ], "type": "object" }, "id": { "description": "Tool call id.", "type": "string" }, "type": { "description": "Tool call type.", "enum": [ "function" ], "type": "string" } }, "required": [ "id", "type", "function" ], "type": "object" }, "CompactionConfig": { "additionalProperties": false, "default": { "enabled": true }, "description": "Uses 80% of the model context length when the explicit trigger is omitted, or 50000 tokens if unknown.", "properties": { "enabled": { "default": true, "description": "Summarize older history when context grows too large. Default: true.", "type": "boolean" }, "trigger": { "$ref": "#/components/schemas/InputTokensCompactionTrigger" } }, "type": "object" }, "CompactionTrigger": { "description": "Why compaction was triggered.", "properties": { "context_tokens": { "description": "Estimated context tokens when compaction fired (prompt + completion).", "minimum": 0, "type": "integer" }, "threshold_tokens": { "description": "Configured compaction threshold in tokens.", "exclusiveMinimum": 0, "type": "integer" }, "type": { "description": "Triggered because estimated context crossed the compaction threshold.", "enum": [ "context_threshold_exceeded" ], "type": "string" } }, "required": [ "type", "context_tokens", "threshold_tokens" ], "type": "object" }, "CompletionUsage": { "description": "Token usage for the compaction model call.", "properties": { "cache_read_tokens": { "description": "Optional cache-read tokens.", "minimum": 0, "type": "integer" }, "cache_write_tokens": { "description": "Optional cache-write tokens.", "minimum": 0, "type": "integer" }, "cost_in_usd": { "description": "Optional estimated cost in USD.", "minimum": 0, "type": "number" }, "input_tokens": { "description": "Input tokens for this completion.", "minimum": 0, "type": "integer" }, "output_tokens": { "description": "Output tokens for this completion.", "minimum": 0, "type": "integer" }, "reasoning_tokens": { "description": "Optional reasoning tokens.", "minimum": 0, "type": "integer" }, "total_tokens": { "description": "Total tokens (input + output).", "minimum": 0, "type": "integer" } }, "required": [ "input_tokens", "output_tokens", "total_tokens" ], "type": "object" }, "Configuration": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/ConfigurationManifest" }, "updated_at": { "description": "When the configuration was last saved.", "format": "date-time", "type": "string" } }, "required": [ "manifest", "updated_at" ], "type": "object" }, "ConfigurationManifest": { "additionalProperties": false, "properties": { "memory": { "$ref": "#/components/schemas/MemoryConfiguration" }, "web_search": { "$ref": "#/components/schemas/WebSearchConfiguration" } }, "required": [ "web_search", "memory" ], "type": "object" }, "ConfigurationManifestPatch": { "additionalProperties": false, "properties": { "memory": { "$ref": "#/components/schemas/MemoryConfiguration" }, "web_search": { "$ref": "#/components/schemas/WebSearchConfiguration" } }, "type": "object" }, "ConfiguredMCPServer": { "additionalProperties": false, "properties": { "auth_status": { "$ref": "#/components/schemas/MCPAuthStatus" }, "manifest": { "$ref": "#/components/schemas/MCPServerManifest" }, "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "name", "manifest", "auth_status" ], "type": "object" }, "ConfiguredMemoryProvider": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/MemoryProviderManifest" }, "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "name", "manifest" ], "type": "object" }, "ConfiguredModel": { "additionalProperties": false, "properties": { "model_id": { "description": "Upstream, provider-specific identifier sent to the provider API.", "minLength": 1, "type": "string" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "properties": { "$ref": "#/components/schemas/ModelProperties" } }, "required": [ "model_id", "name", "properties" ], "type": "object" }, "ConfiguredModelProvider": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/ModelProviderManifest" }, "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "name", "manifest" ], "type": "object" }, "ConfiguredSandboxProvider": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/SandboxProviderManifest" } }, "required": [ "manifest" ], "type": "object" }, "ConfiguredSkill": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/SkillManifest" }, "name": { "minLength": 1, "type": "string" } }, "required": [ "name", "manifest" ], "type": "object" }, "ConfiguredWebSearchProvider": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/WebSearchProviderManifest" }, "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "name", "manifest" ], "type": "object" }, "ContextManagementConfig": { "default": { "compaction": { "enabled": true }, "large_tool_response": { "enabled": true } }, "properties": { "compaction": { "$ref": "#/components/schemas/CompactionConfig" }, "large_tool_response": { "$ref": "#/components/schemas/LargeToolResponseConfig" } }, "type": "object" }, "CreateAgentRequest": { "additionalProperties": false, "properties": { "description": { "maxLength": 1024, "minLength": 1, "type": "string" }, "manifest": { "$ref": "#/components/schemas/AgentSpec" }, "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "name", "description", "manifest" ], "type": "object" }, "CreateMCPServerRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/MCPServerManifest" } }, "required": [ "manifest" ], "type": "object" }, "CreateModelProviderRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/ModelProviderManifest" } }, "required": [ "manifest" ], "type": "object" }, "CreateSandboxEnvironmentRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/SandboxEnvironmentManifestRequest" } }, "required": [ "manifest" ], "type": "object" }, "CreateScheduleRequest": { "additionalProperties": false, "properties": { "agent_name": { "$ref": "#/components/schemas/ResourceName" }, "manifest": { "$ref": "#/components/schemas/ScheduleManifest" }, "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "agent_name", "name", "manifest" ], "type": "object" }, "CreateScheduleRunRequest": { "additionalProperties": false, "description": "Trigger an immediate run for the given schedule. The task is taken from the schedule manifest.", "properties": { "schedule_id": { "description": "Immutable schedule identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "schedule_id" ], "type": "object" }, "CreateScheduleRunResponse": { "properties": { "data": { "$ref": "#/components/schemas/ScheduleRun" } }, "required": [ "data" ], "type": "object" }, "CreateSessionAgent": { "anyOf": [ { "$ref": "#/components/schemas/SessionAgentNameRef" }, { "$ref": "#/components/schemas/SessionAgentSpecBody" } ] }, "CreateSessionRequest": { "additionalProperties": false, "properties": { "agent": { "$ref": "#/components/schemas/CreateSessionAgent" }, "metadata": { "$ref": "#/components/schemas/SessionMetadata" } }, "required": [ "agent" ], "type": "object" }, "CreateSkillRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/SkillManifest" } }, "required": [ "manifest" ], "type": "object" }, "CreateTurnEventRequest": { "properties": { "events": { "description": "One or more user events.", "items": { "$ref": "#/components/schemas/TurnUserEventMessage" }, "minItems": 1, "type": "array" } }, "required": [ "events" ], "type": "object" }, "CreateTurnEventResponse": { "properties": { "data": { "description": "Events with server-minted `id` and `created_at`, in request order.", "items": { "$ref": "#/components/schemas/TurnUserEvent" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "CreateTurnRequest": { "properties": { "input": { "description": "User messages for this turn. At least one is required.", "items": { "allOf": [ { "$ref": "#/components/schemas/UserMessage" }, { "properties": { "content": { "anyOf": [ { "minLength": 1, "type": "string" }, { "items": { "$ref": "#/components/schemas/UserMessageContentItem" }, "type": "array" } ] } }, "type": "object" } ] }, "minItems": 1, "type": "array" }, "previous_turn_id": { "$ref": "#/components/schemas/PreviousTurnIdInput" }, "stream": { "default": true, "description": "When true (default), stream turn events as SSE. When false, return the running turn immediately.", "type": "boolean" } }, "required": [ "input" ], "type": "object" }, "CronExpression": { "description": "Standard 5-field cron expression, evaluated in `timezone`.", "pattern": "^[\\d*,\\-/]+(?:\\s+[\\d*,\\-/]+){4}$", "type": "string" }, "CustomModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "description": "Base URL of the provider's API.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "type": { "enum": [ "custom" ], "type": "string" } }, "required": [ "models", "type", "name", "base_url" ], "type": "object" }, "DaytonaSandboxProviderAuth": { "additionalProperties": false, "description": "Daytona authentication credentials.", "properties": { "api_key": { "description": "Daytona API key. Responses are redacted; on PUT, a real value sets/rotates and a redacted value keeps the stored key.", "minLength": 1, "type": "string" } }, "required": [ "api_key" ], "type": "object" }, "DeleteAgentResponse": { "properties": {}, "type": "object" }, "DeleteMCPServerResponse": { "properties": {}, "type": "object" }, "DeleteModelProviderResponse": { "properties": {}, "type": "object" }, "DeleteSandboxEnvironmentResponse": { "properties": {}, "type": "object" }, "DeleteScheduleResponse": { "properties": {}, "type": "object" }, "DeleteSkillResponse": { "properties": {}, "type": "object" }, "DynamicSubAgentsConfig": { "default": { "enabled": true }, "properties": { "enabled": { "default": true, "description": "Allow the agent to spawn dynamic subagents. Default: true.", "type": "boolean" } }, "type": "object" }, "ExecuteScheduleRunRequest": { "additionalProperties": false, "properties": { "schedule_run_id": { "description": "Immutable schedule run identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "schedule_run_id" ], "type": "object" }, "ExtendedChunkDeltaToolCall": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionChunkDeltaToolCall" }, { "properties": { "provider_specific_fields": { "additionalProperties": {}, "type": "object" }, "tool_info": { "$ref": "#/components/schemas/ToolInfo" } }, "type": "object" } ] }, "FileContent": { "properties": { "data": { "description": "Data URI: `data:;base64,`. MIME type is parsed from the URI.", "type": "string" }, "name": { "description": "Filename presented to the agent.", "type": "string" }, "type": { "description": "File attachment content part.", "enum": [ "file" ], "type": "string" } }, "required": [ "type", "name", "data" ], "type": "object" }, "FinishReason": { "description": "Why the model stopped generating.", "enum": [ "stop", "length", "tool_calls", "content_filter", "function_call" ], "type": "string" }, "FireworksModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "default": "https://api.fireworks.ai/inference/v1", "description": "Override of the provider's default API base URL.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "fireworks" ], "type": "string" } }, "required": [ "auth", "models", "type" ], "type": "object" }, "GenerativeUIConfig": { "default": { "enabled": true }, "properties": { "enabled": { "default": true, "description": "Enable Generative UI (OpenUI blocks). Default: true.", "type": "boolean" } }, "type": "object" }, "GetAgentCodeSnippetsResponse": { "properties": { "data": { "$ref": "#/components/schemas/AgentCodeSnippets" } }, "required": [ "data" ], "type": "object" }, "GetAgentResponse": { "properties": { "data": { "$ref": "#/components/schemas/Agent" } }, "required": [ "data" ], "type": "object" }, "GetAvailableMCPServerResponse": { "properties": { "data": { "$ref": "#/components/schemas/AvailableMCPServer" } }, "required": [ "data" ], "type": "object" }, "GetCapabilitiesResponse": { "properties": { "data": { "$ref": "#/components/schemas/CapabilitiesData" } }, "required": [ "data" ], "type": "object" }, "GetConfigurationResponse": { "properties": { "data": { "$ref": "#/components/schemas/Configuration" } }, "required": [ "data" ], "type": "object" }, "GetMCPServerCatalogResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CatalogMCPServer" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "GetMCPServerResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConfiguredMCPServer" } }, "required": [ "data" ], "type": "object" }, "GetMeResponse": { "properties": { "data": { "$ref": "#/components/schemas/Me" } }, "required": [ "data" ], "type": "object" }, "GetMeSubject": { "properties": { "display_name": { "description": "Human-readable name for the caller.", "type": "string" }, "id": { "description": "Stable subject identifier for the caller.", "type": "string" }, "type": { "description": "Subject kind as returned by the identity provider (stored as-is).", "type": "string" } }, "required": [ "id", "type", "display_name" ], "type": "object" }, "GetMemoryProviderCatalogResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CatalogMemoryProvider" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "GetMemoryProviderResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConfiguredMemoryProvider" } }, "required": [ "data" ], "type": "object" }, "GetModelProviderCatalogResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CatalogModelProvider" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "GetModelProviderResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConfiguredModelProvider" } }, "required": [ "data" ], "type": "object" }, "GetOrCreateSessionByExternalIdRequest": { "additionalProperties": false, "properties": { "agent": { "$ref": "#/components/schemas/CreateSessionAgent" }, "external_id": { "description": "Caller-supplied id unique within the tenant.", "maxLength": 128, "minLength": 1, "type": "string" }, "source": { "$ref": "#/components/schemas/SessionSource" } }, "required": [ "external_id", "agent" ], "type": "object" }, "GetSandboxEnvironmentResponse": { "properties": { "data": { "$ref": "#/components/schemas/SandboxEnvironment" } }, "required": [ "data" ], "type": "object" }, "GetSandboxProviderCatalogResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CatalogSandboxProvider" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "GetSandboxProviderResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConfiguredSandboxProvider" } }, "required": [ "data" ], "type": "object" }, "GetScheduleResponse": { "properties": { "data": { "$ref": "#/components/schemas/Schedule" } }, "required": [ "data" ], "type": "object" }, "GetSessionMetricsChartDataResponse": { "properties": { "data": { "$ref": "#/components/schemas/SessionMetricsChartDataResponse" } }, "required": [ "data" ], "type": "object" }, "GetSessionMetricsChartResponse": { "properties": { "data": { "$ref": "#/components/schemas/SessionMetricsChartResponse" } }, "required": [ "data" ], "type": "object" }, "GetSessionMetricsMeterResponse": { "properties": { "data": { "$ref": "#/components/schemas/SessionMetricsMeterResponse" } }, "required": [ "data" ], "type": "object" }, "GetSessionResponse": { "properties": { "data": { "$ref": "#/components/schemas/Session" } }, "required": [ "data" ], "type": "object" }, "GetSkillCatalogResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CatalogSkill" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "GetSkillResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConfiguredSkill" } }, "required": [ "data" ], "type": "object" }, "GetTurnResponse": { "properties": { "data": { "$ref": "#/components/schemas/Turn" } }, "required": [ "data" ], "type": "object" }, "GetWebSearchProviderCatalogResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CatalogWebSearchProvider" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "GetWebSearchProviderResponse": { "properties": { "data": { "$ref": "#/components/schemas/ConfiguredWebSearchProvider" } }, "required": [ "data" ], "type": "object" }, "GitSkill": { "additionalProperties": false, "properties": { "description": { "description": "Concise guidance for when the agent should use the skill.", "minLength": 1, "type": "string" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "path": { "description": "Path to the skill directory within the repository. Omit to use the repository root.", "minLength": 1, "pattern": "^[A-Za-z0-9._\\-/]+$", "type": "string" }, "ref": { "description": "Git ref — branch name, tag, or commit SHA.", "minLength": 1, "pattern": "^[A-Za-z0-9._\\-/]+$", "type": "string" }, "type": { "enum": [ "git" ], "type": "string" }, "url": { "description": "Full HTTPS URL of a GitHub or GitLab repository.", "minLength": 1, "pattern": "^https:\\/\\/(github\\.com\\/[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+|gitlab\\.com\\/[A-Za-z0-9._-]+(?:\\/[A-Za-z0-9._-]+)+)(\\/|\\.git)?$", "type": "string" } }, "required": [ "type", "name", "url", "ref", "description" ], "type": "object" }, "GoogleGeminiModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "default": "https://generativelanguage.googleapis.com/v1beta", "description": "Override of the provider's default API base URL.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "google-gemini" ], "type": "string" } }, "required": [ "auth", "models", "type" ], "type": "object" }, "InitialUserMessage": { "properties": { "content": { "description": "Initial user message content injected at the start of every session.", "minLength": 1, "type": "string" }, "type": { "description": "Initial message type.", "enum": [ "user.message" ], "type": "string" } }, "required": [ "type", "content" ], "type": "object" }, "InputTokensCompactionTrigger": { "additionalProperties": false, "properties": { "type": { "description": "Trigger compaction when the estimated input reaches a token limit.", "enum": [ "input_tokens" ], "type": "string" }, "value": { "description": "Estimated input-token count that triggers compaction.", "exclusiveMinimum": 0, "type": "integer" } }, "required": [ "type", "value" ], "type": "object" }, "InternalCreateSessionTurnRequest": { "properties": { "input": { "description": "User messages for this turn. At least one is required.", "items": { "allOf": [ { "$ref": "#/components/schemas/UserMessage" }, { "properties": { "content": { "anyOf": [ { "minLength": 1, "type": "string" }, { "items": { "$ref": "#/components/schemas/UserMessageContentItem" }, "type": "array" } ] } }, "type": "object" } ] }, "minItems": 1, "type": "array" }, "previous_turn_id": { "$ref": "#/components/schemas/PreviousTurnIdInput" }, "stream": { "default": false, "description": "Must be false; streaming is not supported on this endpoint.", "enum": [ false ], "type": "boolean" } }, "required": [ "input" ], "type": "object" }, "LargeToolResponseConfig": { "default": { "enabled": true }, "properties": { "enabled": { "default": true, "description": "Offload oversized tool responses to a sandbox file. Default: true.", "type": "boolean" } }, "type": "object" }, "LegacyTurnInputItem": { "discriminator": { "mapping": { "user.message": "#/components/schemas/UserMessage", "user.tool_approval": "#/components/schemas/UserToolApprovalInputEvent", "user.tool_response": "#/components/schemas/UserToolResponseInputEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/UserMessage" }, { "$ref": "#/components/schemas/UserToolApprovalInputEvent" }, { "$ref": "#/components/schemas/UserToolResponseInputEvent" } ] }, "ListAgentsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Agent" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "ListAvailableMCPServersResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AvailableMCPServer" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListAvailableModelsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AvailableModel" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListAvailableSkillsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/AvailableSkill" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListMCPServerToolsResponse": { "properties": { "data": { "description": "MCP `tools/list` entries, passed through verbatim from the MCP server.", "items": { "additionalProperties": {}, "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListMCPServersResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ConfiguredMCPServer" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListModelProvidersResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ConfiguredModelProvider" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListPendingSandboxEnvironmentVersionsResponse": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/PendingSandboxEnvironmentVersion" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListPermissionsData": { "properties": { "permissions": { "additionalProperties": { "items": { "$ref": "#/components/schemas/ResourcePermission" }, "type": "array" }, "description": "Keyed by resource id for resource types, or by entity kind for `tenant` (e.g. `agent` → `CREATE`).", "type": "object" }, "type": { "$ref": "#/components/schemas/PermissionResourceType" } }, "required": [ "type", "permissions" ], "type": "object" }, "ListPermissionsRequest": { "properties": { "resource_ids": { "description": "Resource ids of `resource_type` to evaluate.", "items": { "minLength": 1, "type": "string" }, "maxItems": 100, "type": "array" }, "resource_type": { "$ref": "#/components/schemas/PermissionResourceType" } }, "required": [ "resource_type", "resource_ids" ], "type": "object" }, "ListPermissionsResponse": { "properties": { "data": { "$ref": "#/components/schemas/ListPermissionsData" } }, "required": [ "data" ], "type": "object" }, "ListSandboxEnvironmentsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SandboxEnvironment" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "ListScheduleRunsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ScheduleRun" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "ListSchedulesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Schedule" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "ListSessionEventsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SessionEventItem" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "ListSessionGrantsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SessionGrant" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListSessionsOrder": { "default": "desc", "description": "Sort sessions by `updated_at`. Defaults to \"desc\".", "enum": [ "asc", "desc" ], "type": "string" }, "ListSessionsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Session" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "ListSkillVersionsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SkillVersion" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListSkillsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ConfiguredSkill" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "ListTurnEventsOrder": { "default": "asc", "description": "Sort events by insertion order. Defaults to \"asc\".", "enum": [ "asc", "desc" ], "type": "string" }, "ListTurnEventsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SessionEvent" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "ListTurnsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Turn" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "ListUsersResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/User" }, "type": "array" }, "pagination": { "$ref": "#/components/schemas/TokenPagination" } }, "required": [ "data", "pagination" ], "type": "object" }, "MCPAuthRequiredEvent": { "allOf": [ { "$ref": "#/components/schemas/BaseMCPAuthRequiredEvent" }, { "properties": { "mcp_servers": { "description": "Servers that need authorization, each with an auth_url.", "items": { "$ref": "#/components/schemas/MCPServerAuthInfo" }, "type": "array" }, "type": { "description": "One or more MCP servers need OAuth before tools can run.", "enum": [ "mcp.auth_required" ], "type": "string" } }, "required": [ "type", "mcp_servers" ], "type": "object" } ] }, "MCPAuthStatus": { "additionalProperties": false, "description": "Current auth state.", "properties": { "authorization_url": { "description": "When auth is required, this contains the URL to redirect the user to for authorization.", "format": "uri", "type": "string" }, "status": { "description": "Current auth state for this MCP server.", "enum": [ "authenticated", "auth_required", "not_required" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "MCPInitializeEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "mcp_servers": { "description": "Servers that were initialized.", "items": { "$ref": "#/components/schemas/MCPServerInitInfo" }, "type": "array" }, "thread_id": { "description": "Thread that triggered initialization.", "type": "string" }, "type": { "description": "MCP server(s) initialized for this turn.", "enum": [ "mcp.initialize" ], "type": "string" } }, "required": [ "type", "id", "created_at", "thread_id", "mcp_servers" ], "type": "object" }, "MCPServer": { "properties": { "disable_tools": { "default": [], "description": "Tools subtracted from the enabled set. Default: none.", "items": { "$ref": "#/components/schemas/MCPServerToolSelector" }, "type": "array" }, "enable_tools": { "default": [ "@all" ], "description": "Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. Default: `[\"@all\"]`.", "items": { "$ref": "#/components/schemas/MCPServerToolSelector" }, "type": "array" }, "name": { "description": "Name of a configured MCP server (Settings → Connectors).", "minLength": 1, "type": "string" }, "preload": { "default": false, "description": "When true, load all tool schemas upfront. Default: false (deferred discovery).", "type": "boolean" }, "preload_tools": { "default": [], "description": "Tools loaded eagerly into context while the rest stay deferred. A non-empty list implies `preload: false`.", "items": { "$ref": "#/components/schemas/MCPServerToolSelector" }, "type": "array" }, "require_approval_for_tools": { "default": [ "@write", "@destructive" ], "description": "Tools that pause for human approval: `@all`, `@write`, `@destructive`, or literal names. Default: `[\"@write\", \"@destructive\"]`.", "items": { "$ref": "#/components/schemas/MCPServerApprovalToolSelector" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "MCPServerApprovalToolSelector": { "anyOf": [ { "enum": [ "@all", "@write", "@destructive" ], "type": "string" }, { "minLength": 1, "type": "string" } ] }, "MCPServerAuthInfo": { "properties": { "auth_url": { "description": "URL the user must visit to complete OAuth for this server.", "type": "string" }, "id": { "description": "Internal MCP server id.", "type": "string" }, "name": { "description": "Configured MCP server name.", "type": "string" } }, "required": [ "id", "name", "auth_url" ], "type": "object" }, "MCPServerAuthPublic": { "description": "Auth mechanism when configured (no secrets). Omit when the server needs no credentials.", "oneOf": [ { "additionalProperties": false, "properties": { "type": { "enum": [ "dcr" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, { "additionalProperties": false, "properties": { "type": { "enum": [ "header" ], "type": "string" } }, "required": [ "type" ], "type": "object" } ] }, "MCPServerDcrAuth": { "additionalProperties": false, "properties": { "type": { "description": "Authenticate via OAuth Dynamic Client Registration.", "enum": [ "dcr" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "MCPServerHeaderAuth": { "additionalProperties": false, "properties": { "headers": { "additionalProperties": { "minLength": 1, "type": "string" }, "description": "Request headers for this MCP server. Responses are redacted; on PUT, a real value sets/rotates and a redacted value keeps the stored secret for that header name.", "type": "object" }, "type": { "description": "Authenticate with static HTTP headers.", "enum": [ "header" ], "type": "string" } }, "required": [ "type", "headers" ], "type": "object" }, "MCPServerInitInfo": { "properties": { "approval_policies": { "additionalProperties": { "$ref": "#/components/schemas/ToolApprovalPolicy" }, "description": "Sticky per-tool approval policies (keyed by tool name) that auto-allow future calls.", "type": "object" }, "id": { "description": "Internal MCP server id.", "type": "string" }, "name": { "description": "Configured MCP server name.", "type": "string" }, "session_id": { "description": "Optional MCP session id from the transport.", "type": "string" }, "transport_type": { "description": "Transport used to connect to the MCP server.", "enum": [ "streamable-http", "sse" ], "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "MCPServerManifest": { "discriminator": { "mapping": { "remote": "#/components/schemas/RemoteMCPServerManifest", "truefoundry": "#/components/schemas/TrueFoundryMCPServerManifest" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/RemoteMCPServerManifest" }, { "$ref": "#/components/schemas/TrueFoundryMCPServerManifest" } ] }, "MCPServerManifestAuth": { "description": "Optional auth settings. Omit when the server needs no credentials.", "discriminator": { "mapping": { "dcr": "#/components/schemas/MCPServerDcrAuth", "header": "#/components/schemas/MCPServerHeaderAuth" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/MCPServerHeaderAuth" }, { "$ref": "#/components/schemas/MCPServerDcrAuth" } ] }, "MCPServerToolSelector": { "anyOf": [ { "enum": [ "@all", "@read-only" ], "type": "string" }, { "minLength": 1, "type": "string" } ] }, "MCPToolInfo": { "properties": { "name": { "description": "Tool name on the MCP server.", "type": "string" }, "server_id": { "description": "Internal MCP server id.", "type": "string" }, "server_name": { "description": "Configured MCP server name.", "type": "string" }, "type": { "description": "Tool hosted on an MCP server.", "enum": [ "mcp" ], "type": "string" } }, "required": [ "type", "server_id", "server_name", "name" ], "type": "object" }, "Me": { "properties": { "roles": { "description": "Roles for the authenticated caller.", "items": { "type": "string" }, "type": "array" }, "subject": { "$ref": "#/components/schemas/GetMeSubject" }, "tenant_id": { "description": "Tenant scope for the authenticated caller.", "type": "string" }, "type": { "$ref": "#/components/schemas/MeSessionType" } }, "required": [ "type", "tenant_id", "subject", "roles" ], "type": "object" }, "MeSessionType": { "description": "`oidc-connected` when the process is running with browser OIDC login; `default` for standalone or TrueFoundry token auth.", "enum": [ "default", "oidc-connected" ], "type": "string" }, "MemoryCapability": { "description": "Present only when the tenant has a memory provider; absent means memory settings are hidden.", "properties": { "enabled": { "description": "Whether agents may turn memory on: the tenant allows it.", "type": "boolean" }, "reason": { "description": "Present when memory is unavailable. Explains why.", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "MemoryConfig": { "default": { "enabled": false }, "properties": { "enabled": { "default": false, "description": "Enable long-term memory for this agent. Default: false.", "type": "boolean" } }, "type": "object" }, "MemoryConfiguration": { "additionalProperties": false, "properties": { "enabled": { "description": "Whether agents in this tenant may remember details from past chats.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "MemoryProviderManifest": { "oneOf": [ { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ZepMemoryProviderAuth" }, "server_url": { "description": "Zep API URL. Defaults to Zep Cloud.", "format": "uri", "type": "string" }, "type": { "description": "Zep memory provider.", "enum": [ "zep" ], "type": "string" } }, "required": [ "type", "auth" ], "type": "object" } ] }, "MetricsUnit": { "enum": [ "count", "$", "ms" ], "type": "string", "x-fern-enum": { "$": { "name": "USD" } } }, "Model": { "properties": { "name": { "description": "Model FQN: `provider/model`, e.g. `openai/gpt-5.2`.", "minLength": 1, "type": "string" }, "params": { "$ref": "#/components/schemas/ModelParams" } }, "required": [ "name" ], "type": "object" }, "ModelMessageDeltaEvent": { "properties": { "content": { "description": "Incremental assistant text content.", "type": [ "string", "null" ] }, "created_at": { "description": "Optional ISO 8601 event timestamp.", "type": "string" }, "finish_reason": { "anyOf": [ { "$ref": "#/components/schemas/FinishReason" }, { "type": "null" } ], "description": "Finish reason when this delta completes the stream." }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "reasoning_content": { "type": "string" }, "refusal": { "description": "Incremental refusal text when present.", "type": [ "string", "null" ] }, "thread_id": { "description": "Thread that emitted this delta.", "type": "string" }, "tool_calls": { "items": { "$ref": "#/components/schemas/ExtendedChunkDeltaToolCall" }, "type": "array" }, "type": { "description": "Streaming delta for a model.message.", "enum": [ "model.message.delta" ], "type": "string" }, "usage": { "$ref": "#/components/schemas/ModelMessageUsage" } }, "required": [ "type", "id", "thread_id" ], "type": "object" }, "ModelMessageEvent": { "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "anyOf": [ { "$ref": "#/components/schemas/ChatCompletionContentPartText" }, { "$ref": "#/components/schemas/ChatCompletionContentPartRefusal" } ] }, "type": "array" }, { "type": "null" } ], "description": "Assistant message content as text or content parts." }, "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "finish_reason": { "anyOf": [ { "$ref": "#/components/schemas/FinishReason" }, { "type": "null" } ], "description": "Model finish reason; null when the provider omitted it." }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "model": { "$ref": "#/components/schemas/Model" }, "name": { "description": "Optional participant name.", "type": "string" }, "reasoning_content": { "type": "string" }, "refusal": { "description": "Optional refusal text.", "type": [ "string", "null" ] }, "thread_id": { "description": "Thread that emitted this message (`main` for the root agent).", "type": "string" }, "tool_calls": { "items": { "$ref": "#/components/schemas/ToolCall" }, "type": "array" }, "type": { "description": "Complete assistant model message.", "enum": [ "model.message" ], "type": "string" }, "usage": { "$ref": "#/components/schemas/ModelMessageUsage" } }, "required": [ "type", "id", "thread_id", "created_at" ], "type": "object" }, "ModelMessageUsage": { "properties": { "cache_read_tokens": { "description": "Optional cache-read tokens.", "minimum": 0, "type": "integer" }, "cache_write_tokens": { "description": "Optional cache-write tokens.", "minimum": 0, "type": "integer" }, "input_tokens": { "description": "Input tokens for this model call.", "minimum": 0, "type": "integer" }, "input_tokens_breakdown": { "properties": { "harness": { "description": "Tokens attributed to harness system framing.", "minimum": 0, "type": "integer" }, "instructions": { "description": "Tokens attributed to agent instructions.", "minimum": 0, "type": "integer" }, "messages": { "description": "Tokens attributed to conversation messages.", "minimum": 0, "type": "integer" }, "skills": { "description": "Tokens attributed to skill instructions.", "minimum": 0, "type": "integer" }, "tool_definitions": { "description": "Tokens attributed to tool schemas.", "minimum": 0, "type": "integer" } }, "required": [ "harness", "skills", "instructions", "tool_definitions", "messages" ], "type": "object" }, "output_tokens": { "description": "Output tokens for this model call.", "minimum": 0, "type": "integer" } }, "required": [ "input_tokens", "output_tokens", "input_tokens_breakdown" ], "type": "object" }, "ModelParams": { "additionalProperties": {}, "description": "Model call parameters passed through to the provider. Known keys are documented; extra keys are allowed and forwarded as-is.", "properties": { "max_tokens": { "description": "Maximum tokens to generate in the model response.", "type": "number" }, "parallel_tool_calls": { "description": "Whether the model may emit multiple tool calls in one response.", "type": "boolean" }, "reasoning_effort": { "description": "Provider-specific reasoning effort (e.g. low/medium/high).", "type": "string" }, "temperature": { "description": "Sampling temperature; higher values increase randomness.", "type": "number" }, "top_k": { "description": "Top-k sampling; keep only the k highest-probability tokens.", "type": "number" }, "top_p": { "description": "Nucleus sampling probability mass.", "type": "number" } }, "type": "object" }, "ModelProperties": { "additionalProperties": false, "description": "Optional model capability metadata.", "properties": { "context_length": { "description": "Maximum context window size in tokens.", "exclusiveMinimum": 0, "type": "integer" }, "max_output_tokens": { "description": "Maximum output tokens the model can generate.", "exclusiveMinimum": 0, "type": "integer" }, "reasoning_efforts": { "description": "Supported reasoning-effort values for this model.", "items": { "$ref": "#/components/schemas/ReasoningEffort" }, "minItems": 1, "type": "array" } }, "type": "object" }, "ModelProviderAuth": { "additionalProperties": false, "description": "Provider authentication credentials.", "properties": { "api_key": { "description": "Provider API key. Responses are redacted; on PUT, a real value sets/rotates and a redacted value keeps the stored key.", "minLength": 1, "type": "string" } }, "required": [ "api_key" ], "type": "object" }, "ModelProviderManifest": { "discriminator": { "mapping": { "alibaba": "#/components/schemas/AlibabaModelProvider", "anthropic": "#/components/schemas/AnthropicModelProvider", "custom": "#/components/schemas/CustomModelProvider", "fireworks": "#/components/schemas/FireworksModelProvider", "google-gemini": "#/components/schemas/GoogleGeminiModelProvider", "moonshot": "#/components/schemas/MoonshotModelProvider", "openai": "#/components/schemas/OpenAIModelProvider", "together": "#/components/schemas/TogetherAIModelProvider", "truefoundry": "#/components/schemas/TrueFoundryModelProvider", "zai": "#/components/schemas/ZaiModelProvider" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/OpenAIModelProvider" }, { "$ref": "#/components/schemas/AnthropicModelProvider" }, { "$ref": "#/components/schemas/GoogleGeminiModelProvider" }, { "$ref": "#/components/schemas/FireworksModelProvider" }, { "$ref": "#/components/schemas/ZaiModelProvider" }, { "$ref": "#/components/schemas/MoonshotModelProvider" }, { "$ref": "#/components/schemas/TogetherAIModelProvider" }, { "$ref": "#/components/schemas/AlibabaModelProvider" }, { "$ref": "#/components/schemas/TrueFoundryModelProvider" }, { "$ref": "#/components/schemas/CustomModelProvider" } ] }, "MoonshotModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "default": "https://api.moonshot.ai/v1", "description": "Override of the provider's default API base URL.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "moonshot" ], "type": "string" } }, "required": [ "auth", "models", "type" ], "type": "object" }, "OpenAIModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "default": "https://api.openai.com/v1", "description": "Override of the provider's default API base URL.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "openai" ], "type": "string" } }, "required": [ "auth", "models", "type" ], "type": "object" }, "ParallelWebSearchProviderAuth": { "additionalProperties": false, "description": "Parallel authentication credentials.", "properties": { "api_key": { "description": "Parallel API key. Responses are redacted; on PUT, a real value sets/rotates and a redacted value keeps the stored key.", "minLength": 1, "type": "string" } }, "required": [ "api_key" ], "type": "object" }, "PatchSandboxEnvironmentRequest": { "additionalProperties": false, "properties": { "enabled": { "description": "Whether new chats and agents may select this environment.", "type": "boolean" }, "is_default": { "description": "If true, make this environment the default in new chats and agents.", "type": "boolean" } }, "type": "object" }, "PendingSandboxEnvironmentVersion": { "additionalProperties": false, "properties": { "environment_version_id": { "description": "Version row id to progress.", "minLength": 1, "type": "string" } }, "required": [ "environment_version_id" ], "type": "object" }, "PermissionResourceType": { "description": "Resource type to evaluate permissions for.", "enum": [ "agent", "schedule", "session", "tenant", "sandbox_environment" ], "type": "string" }, "PreviousTurnIdInput": { "anyOf": [ { "enum": [ "auto" ], "type": "string" }, { "enum": [ "none" ], "type": "string" }, { "minLength": 1, "type": "string" } ], "default": "auto", "description": "Defaults to 'auto' (chain to session last turn). Use 'none' for a new root turn." }, "ProgressSandboxEnvironmentVersionRequest": { "additionalProperties": false, "properties": { "environment_version_id": { "description": "Version row id to progress.", "minLength": 1, "type": "string" } }, "required": [ "environment_version_id" ], "type": "object" }, "RawToolCall": { "allOf": [ { "$ref": "#/components/schemas/ChatCompletionMessageToolCall" }, { "properties": { "provider_specific_fields": { "additionalProperties": {}, "type": "object" } }, "type": "object" } ] }, "ReasoningEffort": { "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ], "type": "string" }, "RemoteMCPServerManifest": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/MCPServerManifestAuth" }, "description": { "description": "Concise summary of what this MCP server provides.", "minLength": 1, "type": "string" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "type": { "enum": [ "remote" ], "type": "string" }, "url": { "description": "MCP endpoint URL.", "format": "uri", "type": "string" } }, "required": [ "type", "name", "url", "description" ], "type": "object" }, "RequestErrorResponse": { "properties": { "error": { "properties": { "code": { "description": "Optional machine-readable error code; null when not applicable.", "type": [ "string", "null" ] }, "message": { "description": "Human-readable explanation of the failure.", "type": "string" }, "param": { "description": "Optional request field that caused the error; null when not field-specific.", "type": [ "string", "null" ] }, "type": { "description": "Optional error category (e.g. validation vs conflict).", "type": "string" } }, "required": [ "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "ResourceName": { "maxLength": 64, "minLength": 2, "pattern": "^[a-z][a-z0-9-]{0,62}[a-z0-9]$", "type": "string" }, "ResourcePermission": { "description": "Granted action on a resource id or tenant entity kind.", "enum": [ "USE", "MANAGE", "DELETE", "CREATE" ], "type": "string" }, "ResponseFormat": { "discriminator": { "mapping": { "json_object": "#/components/schemas/ResponseFormatJsonObject", "json_schema": "#/components/schemas/ResponseFormatJsonSchema", "text": "#/components/schemas/ResponseFormatText" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ResponseFormatText" }, { "$ref": "#/components/schemas/ResponseFormatJsonObject" }, { "$ref": "#/components/schemas/ResponseFormatJsonSchema" } ] }, "ResponseFormatJsonObject": { "additionalProperties": {}, "description": "JSON object response format. Extra provider fields are allowed.", "properties": { "type": { "description": "Model must return a JSON object.", "enum": [ "json_object" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "ResponseFormatJsonSchema": { "additionalProperties": {}, "description": "JSON Schema response format. Extra provider fields are allowed.", "properties": { "json_schema": { "additionalProperties": {}, "description": "JSON Schema payload. Extra provider fields are allowed.", "properties": { "description": { "description": "Optional schema description for the model.", "type": "string" }, "name": { "description": "Schema name sent to the provider.", "type": "string" }, "schema": { "additionalProperties": {}, "description": "JSON Schema object for the response.", "type": "object" }, "strict": { "description": "When true, ask the provider to enforce the schema strictly.", "type": [ "boolean", "null" ] } }, "required": [ "name" ], "type": "object" }, "type": { "description": "Model must return JSON matching a schema.", "enum": [ "json_schema" ], "type": "string" } }, "required": [ "type", "json_schema" ], "type": "object" }, "ResponseFormatText": { "additionalProperties": {}, "description": "Default text response format. Extra provider fields are allowed.", "properties": { "type": { "description": "Unconstrained text output.", "enum": [ "text" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "RuntimeConfig": { "default": { "ask_user_questions": { "enabled": true }, "context_management": { "compaction": { "enabled": true }, "large_tool_response": { "enabled": true } }, "dynamic_sub_agents": { "enabled": true }, "generative_ui": { "enabled": true }, "iteration_limit": 512, "memory": { "enabled": false }, "sandbox": { "enabled": false, "file_downloads": true }, "web_search": { "enabled": false } }, "properties": { "ask_user_questions": { "$ref": "#/components/schemas/AskUserQuestionsConfig" }, "context_management": { "$ref": "#/components/schemas/ContextManagementConfig" }, "dynamic_sub_agents": { "$ref": "#/components/schemas/DynamicSubAgentsConfig" }, "generative_ui": { "$ref": "#/components/schemas/GenerativeUIConfig" }, "iteration_limit": { "default": 512, "description": "Max agent-loop iterations per turn (1–1024). Default: 512.", "exclusiveMinimum": 0, "maximum": 1024, "type": "integer" }, "memory": { "$ref": "#/components/schemas/MemoryConfig" }, "sandbox": { "$ref": "#/components/schemas/SandboxConfig" }, "web_search": { "$ref": "#/components/schemas/WebSearchConfig" } }, "type": "object" }, "SandboxCapability": { "properties": { "enabled": { "description": "Whether a sandbox provider is configured for this tenant.", "type": "boolean" }, "environments": { "$ref": "#/components/schemas/SandboxEnvironmentsCapability" } }, "required": [ "enabled", "environments" ], "type": "object" }, "SandboxConfig": { "default": { "enabled": false, "file_downloads": true }, "properties": { "enabled": { "description": "Give the agent a sandbox. Required for skills and Code Mode.", "type": "boolean" }, "environment_name": { "description": "Name of a configured sandbox environment to use. Must exist when set.", "minLength": 1, "type": "string" }, "file_downloads": { "default": true, "description": "Allow downloading agent-produced files via the turn download endpoint. Default: true.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "SandboxCreatedEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "sandbox_id": { "description": "Provider sandbox id.", "type": "string" }, "thread_id": { "description": "Always null — sandbox is session-scoped.", "type": [ "string", "null" ] }, "type": { "description": "A sandbox was created for this session.", "enum": [ "sandbox.created" ], "type": "string" } }, "required": [ "type", "id", "created_at", "sandbox_id", "thread_id" ], "type": "object" }, "SandboxEnvironment": { "additionalProperties": false, "properties": { "created_at": { "description": "ISO-8601 create time.", "format": "date-time", "type": "string" }, "created_by_subject": { "$ref": "#/components/schemas/Subject" }, "description": { "description": "Human-readable description; empty when unset.", "type": "string" }, "enabled": { "description": "Whether new chats and agents may select this environment.", "type": "boolean" }, "id": { "description": "Immutable server-generated environment identifier.", "minLength": 1, "type": "string" }, "is_default": { "description": "If true, environment is selected by default in new chats and agents.", "type": "boolean" }, "lifecycle_stage": { "$ref": "#/components/schemas/SandboxEnvironmentLifecycleStage" }, "manifest": { "$ref": "#/components/schemas/SandboxEnvironmentManifest" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "status": { "$ref": "#/components/schemas/SandboxEnvironmentVersionStatus" }, "status_reason": { "description": "Failure detail when status is failed; null otherwise.", "type": [ "string", "null" ] }, "updated_at": { "description": "ISO-8601 last update time.", "format": "date-time", "type": "string" } }, "required": [ "id", "name", "description", "lifecycle_stage", "enabled", "is_default", "status", "status_reason", "manifest", "created_by_subject", "created_at", "updated_at" ], "type": "object" }, "SandboxEnvironmentImage": { "additionalProperties": false, "properties": { "build_script": { "description": "Shell script used to build the snapshot.", "example": "set -ex\npip install httpx\n", "minLength": 1, "type": "string" }, "type": { "description": "Build a snapshot from a script.", "enum": [ "build" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "SandboxEnvironmentLifecycleStage": { "description": "Soft-delete lifecycle stage.", "enum": [ "active", "deleted" ], "type": "string" }, "SandboxEnvironmentManifest": { "additionalProperties": false, "properties": { "description": { "description": "Optional human-readable description.", "maxLength": 1024, "type": "string" }, "environment_variables": { "additionalProperties": { "maxLength": 4096, "minLength": 1, "type": "string" }, "type": "object" }, "image": { "$ref": "#/components/schemas/SandboxEnvironmentImage" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "networking": { "$ref": "#/components/schemas/SandboxEnvironmentNetworking" }, "resources": { "$ref": "#/components/schemas/SandboxEnvironmentResources" } }, "required": [ "name" ], "type": "object" }, "SandboxEnvironmentManifestRequest": { "additionalProperties": false, "properties": { "description": { "description": "Optional human-readable description.", "maxLength": 1024, "type": "string" }, "environment_variables": { "additionalProperties": { "maxLength": 4096, "minLength": 1, "type": "string" }, "type": "object" }, "image": { "$ref": "#/components/schemas/SandboxEnvironmentImage" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "networking": { "$ref": "#/components/schemas/SandboxEnvironmentNetworking" }, "resources": { "$ref": "#/components/schemas/SandboxEnvironmentResources" } }, "required": [ "name" ], "type": "object" }, "SandboxEnvironmentNetworking": { "additionalProperties": false, "properties": { "domain_allow_list": { "description": "Comma-separated allowed domains.", "maxLength": 1024, "minLength": 1, "type": "string" }, "network_block_all": { "description": "Block all outbound network access. When true, domain_allow_list and secrets are not used.", "type": "boolean" }, "secrets": { "description": "Network-scoped secrets.", "items": { "$ref": "#/components/schemas/SandboxEnvironmentSecret" }, "maxItems": 1024, "type": "array" } }, "type": "object" }, "SandboxEnvironmentResources": { "additionalProperties": false, "default": { "cpu": 1, "disk": 3, "memory": 1 }, "properties": { "cpu": { "default": 1, "description": "CPU allocation in cores.", "exclusiveMinimum": 0, "type": "number" }, "disk": { "default": 3, "description": "Disk allocation in GiB.", "exclusiveMinimum": 0, "type": "number" }, "memory": { "default": 1, "description": "Memory allocation in GiB.", "exclusiveMinimum": 0, "type": "number" } }, "type": "object" }, "SandboxEnvironmentSecret": { "additionalProperties": false, "properties": { "env": { "description": "Environment variable name injected into the sandbox.", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "type": "string" }, "hosts": { "description": "Hosts this secret may be sent to.", "items": { "minLength": 1, "type": "string" }, "type": "array" }, "value": { "description": "Secret value; GET responses use a redacted stand-in.", "minLength": 1, "type": "string" } }, "required": [ "env", "value", "hosts" ], "type": "object" }, "SandboxEnvironmentVersionStatus": { "description": "Readiness of the environment.", "enum": [ "pending", "ready", "failed" ], "type": "string" }, "SandboxEnvironmentsCapability": { "properties": { "enabled": { "description": "Whether sandbox environments (snapshots / Environments UI) are available for this tenant.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "SandboxProviderManifest": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/DaytonaSandboxProviderAuth" }, "auto_archive_interval_in_minutes": { "description": "Minutes before Daytona auto-archives the sandbox (0 disables).", "minimum": 0, "type": "integer" }, "auto_delete_interval_in_minutes": { "description": "Minutes before Daytona auto-deletes the sandbox (0 disables).", "minimum": 0, "type": "integer" }, "auto_stop_interval_in_minutes": { "description": "Minutes of idle time before Daytona auto-stops the sandbox (0 disables).", "minimum": 0, "type": "integer" }, "exec_timeout_ms": { "description": "Default sandbox command exec timeout in milliseconds.", "exclusiveMinimum": 0, "type": "integer" }, "type": { "description": "Daytona sandbox provider.", "enum": [ "daytona" ], "type": "string" } }, "required": [ "type", "auth", "exec_timeout_ms", "auto_stop_interval_in_minutes", "auto_archive_interval_in_minutes", "auto_delete_interval_in_minutes" ], "type": "object" }, "Schedule": { "additionalProperties": false, "properties": { "agent_name": { "$ref": "#/components/schemas/ResourceName" }, "created_at": { "format": "date-time", "type": "string" }, "created_by_subject": { "$ref": "#/components/schemas/Subject" }, "id": { "type": "string" }, "manifest": { "$ref": "#/components/schemas/ScheduleManifest" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "agent_name", "name", "manifest", "created_by_subject", "created_at", "updated_at" ], "type": "object" }, "ScheduleManifest": { "additionalProperties": false, "properties": { "cron": { "$ref": "#/components/schemas/CronExpression" }, "status": { "$ref": "#/components/schemas/ScheduleStatus" }, "task": { "description": "First user message sent to the agent on every run.", "minLength": 1, "type": "string" }, "timezone": { "$ref": "#/components/schemas/Timezone" } }, "required": [ "task", "cron" ], "type": "object" }, "ScheduleRun": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by_subject": { "$ref": "#/components/schemas/Subject" }, "id": { "type": "string" }, "name": { "type": "string" }, "reason": { "type": [ "string", "null" ] }, "schedule_id": { "type": "string" }, "scheduled_for": { "format": "date-time", "type": "string" }, "session_id": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ScheduleRunStatus" }, "triggered_at": { "format": "date-time", "type": [ "string", "null" ] }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "schedule_id", "name", "scheduled_for", "status", "created_by_subject", "triggered_at", "reason", "session_id", "created_at", "updated_at" ], "type": "object" }, "ScheduleRunStatus": { "enum": [ "scheduled", "triggered", "failed" ], "type": "string" }, "ScheduleStatus": { "default": "active", "enum": [ "active", "paused" ], "type": "string" }, "Session": { "properties": { "agent": { "$ref": "#/components/schemas/SessionAgent" }, "created_at": { "description": "ISO 8601 creation timestamp.", "type": "string" }, "created_by_subject": { "$ref": "#/components/schemas/Subject" }, "id": { "description": "Unique session id.", "type": "string" }, "last_turn_details": { "$ref": "#/components/schemas/SessionLastTurnDetails" }, "metadata": { "$ref": "#/components/schemas/SessionMetadata" }, "metrics": { "$ref": "#/components/schemas/SessionMetrics" }, "source": { "$ref": "#/components/schemas/SessionSource" }, "title": { "description": "Optional human-readable title; null until set.", "type": [ "string", "null" ] }, "updated_at": { "description": "ISO 8601 last-update timestamp.", "type": "string" } }, "required": [ "id", "agent", "title", "created_by_subject", "created_at", "updated_at", "metrics", "metadata", "source", "last_turn_details" ], "type": "object" }, "SessionAgent": { "discriminator": { "mapping": { "inline": "#/components/schemas/SessionAgentInline", "reference": "#/components/schemas/SessionAgentReference" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/SessionAgentReference" }, { "$ref": "#/components/schemas/SessionAgentInline" } ] }, "SessionAgentInline": { "additionalProperties": false, "properties": { "spec": { "$ref": "#/components/schemas/AgentSpec" }, "type": { "description": "Bind the session to an inline AgentSpec (not a registry id).", "enum": [ "inline" ], "type": "string" } }, "required": [ "type", "spec" ], "type": "object" }, "SessionAgentNameRef": { "additionalProperties": false, "properties": { "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "name" ], "type": "object" }, "SessionAgentReference": { "additionalProperties": false, "properties": { "id": { "description": "Registry agent id.", "minLength": 1, "type": "string" }, "name": { "description": "Create-time snapshot of the registry agent name; null for legacy or orphan rows.", "type": [ "string", "null" ] }, "type": { "description": "Bind the session to a named registry agent.", "enum": [ "reference" ], "type": "string" } }, "required": [ "type", "id", "name" ], "type": "object" }, "SessionAgentSpecBody": { "additionalProperties": false, "properties": { "spec": { "$ref": "#/components/schemas/AgentSpec" } }, "required": [ "spec" ], "type": "object" }, "SessionEvent": { "discriminator": { "mapping": { "mcp.auth_required": "#/components/schemas/MCPAuthRequiredEvent", "mcp.initialize": "#/components/schemas/MCPInitializeEvent", "model.message": "#/components/schemas/ModelMessageEvent", "sandbox.created": "#/components/schemas/SandboxCreatedEvent", "thread.context_compaction_finished": "#/components/schemas/ThreadContextCompactionFinishedEvent", "thread.context_compaction_started": "#/components/schemas/ThreadContextCompactionStartedEvent", "thread.created": "#/components/schemas/ThreadCreatedEvent", "thread.done": "#/components/schemas/ThreadDoneEvent", "tool.approval_required": "#/components/schemas/ToolApprovalRequiredEvent", "tool.response": "#/components/schemas/ToolResponseEvent", "tool.response_required": "#/components/schemas/ToolResponseRequiredEvent", "turn.created": "#/components/schemas/TurnCreatedEvent", "turn.done": "#/components/schemas/TurnDoneEvent", "turn.update": "#/components/schemas/TurnUpdateEvent", "user.mcp_auth_continue": "#/components/schemas/UserMCPAuthContinueEvent", "user.tool_approval": "#/components/schemas/UserToolApprovalEvent", "user.tool_approval_policy": "#/components/schemas/UserToolApprovalPolicyEvent", "user.tool_response": "#/components/schemas/UserToolResponseEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/TurnCreatedEvent" }, { "$ref": "#/components/schemas/TurnUpdateEvent" }, { "$ref": "#/components/schemas/TurnDoneEvent" }, { "$ref": "#/components/schemas/ModelMessageEvent" }, { "$ref": "#/components/schemas/ToolResponseEvent" }, { "$ref": "#/components/schemas/ThreadCreatedEvent" }, { "$ref": "#/components/schemas/ThreadDoneEvent" }, { "$ref": "#/components/schemas/ThreadContextCompactionStartedEvent" }, { "$ref": "#/components/schemas/ThreadContextCompactionFinishedEvent" }, { "$ref": "#/components/schemas/MCPAuthRequiredEvent" }, { "$ref": "#/components/schemas/MCPInitializeEvent" }, { "$ref": "#/components/schemas/SandboxCreatedEvent" }, { "$ref": "#/components/schemas/ToolApprovalRequiredEvent" }, { "$ref": "#/components/schemas/ToolResponseRequiredEvent" }, { "$ref": "#/components/schemas/UserToolApprovalEvent" }, { "$ref": "#/components/schemas/UserToolResponseEvent" }, { "$ref": "#/components/schemas/UserToolApprovalPolicyEvent" }, { "$ref": "#/components/schemas/UserMCPAuthContinueEvent" } ] }, "SessionEventItem": { "properties": { "event": { "$ref": "#/components/schemas/SessionEvent" }, "turn_id": { "description": "Turn that emitted this event.", "type": "string" } }, "required": [ "turn_id", "event" ], "type": "object" }, "SessionGrant": { "additionalProperties": false, "properties": { "created_at": { "description": "When the session was shared with the subject (ISO-8601 UTC).", "type": "string" }, "granted_by_subject": { "$ref": "#/components/schemas/Subject" }, "subject": { "$ref": "#/components/schemas/SessionGrantSubject" } }, "required": [ "subject", "granted_by_subject", "created_at" ], "type": "object" }, "SessionGrantSubject": { "additionalProperties": false, "description": "Who the session is shared with.", "properties": { "subject_id": { "description": "ID of the subject.", "maxLength": 255, "minLength": 1, "type": "string" }, "subject_type": { "$ref": "#/components/schemas/SessionGrantSubjectType" } }, "required": [ "subject_type", "subject_id" ], "type": "object" }, "SessionGrantSubjectType": { "description": "Kind of subject. A `tenant` subject shares the session with everyone in the tenant.", "enum": [ "user", "tenant" ], "type": "string" }, "SessionLastTurnDetails": { "additionalProperties": false, "description": "The session's most recent turn; null until the first turn.", "properties": { "id": { "description": "Id of the last turn.", "minLength": 1, "type": "string" }, "state": { "$ref": "#/components/schemas/SessionLastTurnState" } }, "required": [ "id", "state" ], "type": [ "object", "null" ] }, "SessionLastTurnState": { "properties": { "status": { "$ref": "#/components/schemas/TurnStatus" } }, "required": [ "status" ], "type": "object" }, "SessionMetadata": { "additionalProperties": { "description": "Metadata value; at most 128 characters.", "maxLength": 128, "type": "string" }, "description": "Caller-owned session metadata", "type": "object" }, "SessionMetrics": { "additionalProperties": false, "description": "Rolled-up cost, duration, and turn counters for a session.", "properties": { "total_cost_in_usd": { "description": "Estimated total cost in USD for this session", "minimum": 0, "type": "number" }, "total_duration_ms": { "minimum": 0, "type": "integer" }, "total_turns": { "minimum": 0, "type": "integer" } }, "required": [ "total_duration_ms", "total_turns" ], "type": "object" }, "SessionMetricsChart": { "additionalProperties": false, "properties": { "chart_type": { "enum": [ "line" ], "type": "string" }, "description": { "type": "string" }, "display_name": { "type": "string" }, "name": { "$ref": "#/components/schemas/SessionMetricsChartName" } }, "required": [ "name", "display_name", "description", "chart_type" ], "type": "object" }, "SessionMetricsChartDataResponse": { "additionalProperties": false, "properties": { "graphs": { "items": { "$ref": "#/components/schemas/SessionMetricsGraph" }, "type": "array" }, "step": { "type": "string" } }, "required": [ "step", "graphs" ], "type": "object" }, "SessionMetricsChartName": { "description": "Session metrics chart to return.", "enum": [ "sessions_over_time", "sessions_cost_over_time", "turns_over_time" ], "type": "string" }, "SessionMetricsChartResponse": { "additionalProperties": false, "properties": { "charts": { "items": { "$ref": "#/components/schemas/SessionMetricsChart" }, "type": "array" } }, "required": [ "charts" ], "type": "object" }, "SessionMetricsGraph": { "additionalProperties": false, "properties": { "chart_type": { "enum": [ "line" ], "type": "string" }, "description": { "type": "string" }, "display_name": { "type": "string" }, "graph_lines": { "items": { "$ref": "#/components/schemas/SessionMetricsGraphLine" }, "type": "array" }, "name": { "$ref": "#/components/schemas/SessionMetricsChartName" }, "unit": { "$ref": "#/components/schemas/MetricsUnit" } }, "required": [ "name", "display_name", "description", "unit", "chart_type", "graph_lines" ], "type": "object" }, "SessionMetricsGraphLine": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "values": { "items": { "$ref": "#/components/schemas/SessionMetricsPoint" }, "type": "array" } }, "required": [ "name", "values" ], "type": "object" }, "SessionMetricsMeter": { "additionalProperties": false, "properties": { "aggregate_value": { "minimum": 0, "type": "number" }, "description": { "type": "string" }, "name": { "enum": [ "total_sessions", "total_cost_in_usd", "total_turns", "cost_per_session_in_usd", "avg_turns_per_session", "min_turns_per_session", "max_turns_per_session", "median_turns_per_session", "min_session_duration_ms", "max_session_duration_ms", "median_session_duration_ms", "p95_session_duration_ms" ], "type": "string" }, "unit": { "$ref": "#/components/schemas/MetricsUnit" } }, "required": [ "name", "aggregate_value", "description", "unit" ], "type": "object" }, "SessionMetricsMeterResponse": { "additionalProperties": false, "properties": { "meters": { "items": { "$ref": "#/components/schemas/SessionMetricsMeter" }, "type": "array" } }, "required": [ "meters" ], "type": "object" }, "SessionMetricsPoint": { "additionalProperties": false, "properties": { "timestamp": { "type": "string" }, "value": { "minimum": 0, "type": "number" } }, "required": [ "timestamp", "value" ], "type": "object" }, "SessionSharingCapability": { "properties": { "granularity": { "description": "The finest supported sharing scope. Subject allows sharing with specific users; tenant-wide sharing is always available.", "enum": [ "tenant", "subject" ], "type": "string" } }, "required": [ "granularity" ], "type": "object" }, "SessionSource": { "description": "How this session was created (e.g. a schedule run). Null for interactive sessions.", "oneOf": [ { "$ref": "#/components/schemas/SessionSourceSchedule" }, { "$ref": "#/components/schemas/SessionSourceService" }, { "type": "null" } ] }, "SessionSourceSchedule": { "additionalProperties": false, "properties": { "id": { "description": "Schedule id.", "minLength": 1, "type": "string" }, "run_id": { "description": "Schedule run id.", "minLength": 1, "type": "string" }, "type": { "description": "Session was created by a schedule run.", "enum": [ "schedule" ], "type": "string" } }, "required": [ "type", "id", "run_id" ], "type": "object" }, "SessionSourceService": { "additionalProperties": false, "properties": { "type": { "description": "Session was created by a service caller (service API key create-turn).", "enum": [ "service" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "SessionSourceType": { "description": "When set, returns only sessions created by this source type.", "enum": [ "schedule", "service" ], "type": "string" }, "SettingsCapability": { "properties": { "mcp_servers": { "$ref": "#/components/schemas/SettingsCapabilitySection" }, "memory_providers": { "$ref": "#/components/schemas/SettingsCapabilitySection" }, "model_providers": { "$ref": "#/components/schemas/SettingsCapabilitySection" }, "sandbox_providers": { "$ref": "#/components/schemas/SettingsCapabilitySection" }, "skills": { "$ref": "#/components/schemas/SettingsCapabilitySection" }, "web_search": { "$ref": "#/components/schemas/SettingsCapabilitySection" } }, "required": [ "model_providers", "mcp_servers", "skills", "sandbox_providers", "web_search", "memory_providers" ], "type": "object" }, "SettingsCapabilitySection": { "properties": { "enabled": { "description": "Whether this settings section is available to the caller.", "type": "boolean" }, "manage_providers": { "description": "Whether the caller may add or edit providers in this section. False when the platform owns them.", "type": "boolean" } }, "required": [ "enabled", "manage_providers" ], "type": "object" }, "Skill": { "additionalProperties": false, "properties": { "name": { "description": "Skill name.", "minLength": 1, "pattern": "^[A-Za-z0-9._\\-/:]+$", "type": "string" }, "preload": { "default": false, "description": "Inline SKILL.md into the prompt.", "type": "boolean" } }, "required": [ "name" ], "type": "object" }, "SkillCapability": { "properties": { "enabled": { "description": "Whether skills are available. False when sandbox is not enabled (skills require a sandbox).", "type": "boolean" }, "reason": { "description": "Present when skills are disabled. Explains why.", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "SkillManifest": { "discriminator": { "mapping": { "git": "#/components/schemas/GitSkill", "truefoundry": "#/components/schemas/TrueFoundryRegistrySkill" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/GitSkill" }, { "$ref": "#/components/schemas/TrueFoundryRegistrySkill" } ] }, "SkillVersion": { "additionalProperties": false, "properties": { "description": { "description": "Concise guidance for when the agent should use the skill.", "minLength": 1, "type": "string" }, "display_name": { "minLength": 1, "type": "string" }, "name": { "minLength": 1, "type": "string" }, "version": { "exclusiveMinimum": 0, "type": "integer" } }, "required": [ "name", "display_name", "description", "version" ], "type": "object" }, "Subject": { "additionalProperties": false, "description": "Identity of a subject.", "properties": { "subject_display_name": { "description": "Display name.", "minLength": 1, "type": "string" }, "subject_id": { "description": "Subject id.", "minLength": 1, "type": "string" }, "subject_type": { "description": "Subject type.", "minLength": 1, "type": "string" } }, "required": [ "subject_id", "subject_type", "subject_display_name" ], "type": "object" }, "TextContent": { "properties": { "text": { "description": "Plain-text content.", "type": "string" }, "type": { "description": "Text content part.", "enum": [ "text" ], "type": "string" } }, "required": [ "type", "text" ], "type": "object" }, "ThreadContextCompactionFinishedEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "duration_ms": { "description": "Wall time of the compaction model call in milliseconds.", "minimum": 0, "type": "integer" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "thread_id": { "description": "Thread whose context was compacted.", "type": "string" }, "trigger": { "$ref": "#/components/schemas/CompactionTrigger" }, "type": { "description": "Thread context compaction finished; context overwrite follows.", "enum": [ "thread.context_compaction_finished" ], "type": "string" }, "usage": { "$ref": "#/components/schemas/CompletionUsage" } }, "required": [ "type", "id", "created_at", "thread_id", "trigger", "usage", "duration_ms" ], "type": "object" }, "ThreadContextCompactionStartedEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "thread_id": { "description": "Thread whose context is being compacted.", "type": "string" }, "trigger": { "$ref": "#/components/schemas/CompactionTrigger" }, "type": { "description": "Thread context compaction started; may take noticeable time.", "enum": [ "thread.context_compaction_started" ], "type": "string" } }, "required": [ "type", "id", "created_at", "thread_id", "trigger" ], "type": "object" }, "ThreadCreatedEvent": { "properties": { "agent_info": { "$ref": "#/components/schemas/AgentInfo" }, "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "parent": { "$ref": "#/components/schemas/AgentParent" }, "thread_id": { "description": "Id of the new thread.", "type": "string" }, "title": { "description": "Human-readable thread title.", "type": "string" }, "type": { "description": "A dynamic subagent thread was created.", "enum": [ "thread.created" ], "type": "string" } }, "required": [ "type", "id", "agent_info", "created_at", "parent", "thread_id", "title" ], "type": "object" }, "ThreadDoneEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "parent": { "$ref": "#/components/schemas/AgentParent" }, "state": { "$ref": "#/components/schemas/ThreadState" }, "thread_id": { "description": "Thread that finished.", "type": "string" }, "title": { "description": "Human-readable thread title.", "type": "string" }, "type": { "description": "A thread reached a terminal state.", "enum": [ "thread.done" ], "type": "string" } }, "required": [ "type", "id", "created_at", "thread_id", "title", "state" ], "type": "object" }, "ThreadState": { "discriminator": { "mapping": { "done": "#/components/schemas/ThreadStateDone", "error": "#/components/schemas/ThreadStateError" }, "propertyName": "status" }, "oneOf": [ { "$ref": "#/components/schemas/ThreadStateDone" }, { "$ref": "#/components/schemas/ThreadStateError" } ] }, "ThreadStateDone": { "properties": { "output": { "$ref": "#/components/schemas/ModelMessageEvent" }, "status": { "description": "Thread completed successfully.", "enum": [ "done" ], "type": "string" } }, "required": [ "status", "output" ], "type": "object" }, "ThreadStateError": { "properties": { "error": { "description": "Human-readable error message.", "type": "string" }, "output": { "$ref": "#/components/schemas/ModelMessageEvent" }, "status": { "description": "Thread ended with an error.", "enum": [ "error" ], "type": "string" } }, "required": [ "status", "error" ], "type": "object" }, "Timezone": { "default": "UTC", "description": "IANA time zone the cron expression is evaluated in.", "minLength": 1, "type": "string" }, "TogetherAIModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "default": "https://api.together.xyz/v1", "description": "Override of the provider's default API base URL.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "together" ], "type": "string" } }, "required": [ "auth", "models", "type" ], "type": "object" }, "TokenPagination": { "properties": { "limit": { "description": "Page size used for this response.", "exclusiveMinimum": 0, "type": "integer" }, "next_page_token": { "description": "Opaque token for the next page. Omit or absent when there is no next page.", "type": "string" }, "previous_page_token": { "description": "Opaque token for the previous page. Omit or absent when there is no previous page.", "type": "string" } }, "required": [ "limit" ], "type": "object" }, "ToolApprovalPolicy": { "discriminator": { "mapping": { "allow_session": "#/components/schemas/ToolApprovalPolicyAllowSession" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ToolApprovalPolicyAllowSession" } ] }, "ToolApprovalPolicyAllowSession": { "properties": { "expire_at": { "description": "ISO 8601 timestamp when this session allow expires. Omit to allow for the whole session.", "type": "string" }, "type": { "description": "Allow matching tool calls for the rest of this session.", "enum": [ "allow_session" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "ToolApprovalPolicyItem": { "properties": { "name": { "description": "Tool name on that server.", "minLength": 1, "type": "string" }, "policy": { "$ref": "#/components/schemas/ToolApprovalPolicy" }, "server_name": { "description": "MCP server name.", "minLength": 1, "type": "string" } }, "required": [ "server_name", "name", "policy" ], "type": "object" }, "ToolApprovalRequiredEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "thread_id": { "description": "Thread that owns the pending tool calls.", "type": "string" }, "tool_calls": { "description": "Tool calls waiting for approval.", "items": { "$ref": "#/components/schemas/ToolCallRef" }, "type": "array" }, "type": { "description": "One or more tool calls need human approval.", "enum": [ "tool.approval_required" ], "type": "string" } }, "required": [ "type", "id", "created_at", "thread_id", "tool_calls" ], "type": "object" }, "ToolCall": { "allOf": [ { "$ref": "#/components/schemas/RawToolCall" }, { "properties": { "tool_info": { "$ref": "#/components/schemas/ToolInfo" } }, "required": [ "tool_info" ], "type": "object" } ] }, "ToolCallRef": { "properties": { "id": { "description": "Tool call id awaiting action.", "type": "string" }, "source_event_id": { "description": "Event id of the model.message that requested the tool call.", "type": "string" } }, "required": [ "id", "source_event_id" ], "type": "object" }, "ToolInfo": { "discriminator": { "mapping": { "mcp": "#/components/schemas/MCPToolInfo", "truefoundry-system": "#/components/schemas/TrueFoundrySystemToolInfo" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/TrueFoundrySystemToolInfo" }, { "$ref": "#/components/schemas/MCPToolInfo" } ] }, "ToolResponseEvent": { "properties": { "content": { "type": "string" }, "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "thread_id": { "description": "Thread that owns the tool call.", "type": "string" }, "tool_call_id": { "description": "Id of the tool call this message responds to.", "type": "string" }, "type": { "description": "Result of a tool execution.", "enum": [ "tool.response" ], "type": "string" } }, "required": [ "tool_call_id", "content", "type", "id", "thread_id", "created_at" ], "type": "object" }, "ToolResponseRequiredEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "thread_id": { "description": "Thread that owns the pending tool calls.", "type": "string" }, "tool_calls": { "description": "Tool calls waiting for a client response.", "items": { "$ref": "#/components/schemas/ToolCallRef" }, "type": "array" }, "type": { "description": "One or more client-side tool calls need a user/tool response.", "enum": [ "tool.response_required" ], "type": "string" } }, "required": [ "type", "id", "created_at", "thread_id", "tool_calls" ], "type": "object" }, "TrueFoundryMCPServerManifest": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/MCPServerManifestAuth" }, "description": { "description": "Concise summary of what this MCP server provides.", "minLength": 1, "type": "string" }, "name": { "$ref": "#/components/schemas/ResourceName" }, "type": { "enum": [ "truefoundry" ], "type": "string" }, "url": { "description": "Resolved AI Gateway proxy URL for this TrueFoundry-managed MCP server.", "format": "uri", "type": "string" } }, "required": [ "type", "name", "url", "description" ], "type": "object" }, "TrueFoundryModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "description": "Base URL of the TrueFoundry AI gateway the models are invoked against.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "truefoundry" ], "type": "string" } }, "required": [ "models", "type", "base_url" ], "type": "object" }, "TrueFoundryRegistrySkill": { "additionalProperties": false, "properties": { "description": { "description": "Concise guidance for when the agent should use the skill.", "minLength": 1, "type": "string" }, "display_name": { "minLength": 1, "type": "string" }, "name": { "minLength": 1, "type": "string" }, "repository_name": { "description": "Repo where the skill is registered.", "minLength": 1, "type": "string" }, "type": { "enum": [ "truefoundry" ], "type": "string" }, "version": { "exclusiveMinimum": 0, "type": "integer" } }, "required": [ "type", "name", "display_name", "description", "repository_name", "version" ], "type": "object" }, "TrueFoundrySystemToolInfo": { "properties": { "name": { "description": "System tool name.", "type": "string" }, "type": { "description": "Built-in harness system tool.", "enum": [ "truefoundry-system" ], "type": "string" } }, "required": [ "type", "name" ], "type": "object" }, "Turn": { "properties": { "created_at": { "description": "ISO 8601 creation timestamp.", "type": "string" }, "id": { "description": "Unique turn id.", "type": "string" }, "input": { "description": "Inputs stored when the turn was created, including legacy continuation inputs.", "items": { "$ref": "#/components/schemas/LegacyTurnInputItem" }, "type": "array" }, "previous_turn_id": { "description": "Prior turn this turn chains from; null for a root turn.", "type": [ "string", "null" ] }, "session_id": { "description": "Session that owns this turn.", "type": "string" }, "state": { "$ref": "#/components/schemas/TurnState" } }, "required": [ "id", "session_id", "previous_turn_id", "state", "created_at" ], "type": "object" }, "TurnCreatedEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "input": { "description": "Inputs stored when the turn was created, including legacy continuation inputs.", "items": { "$ref": "#/components/schemas/LegacyTurnInputItem" }, "type": "array" }, "previous_turn_id": { "description": "Prior turn this turn chains from; null for a root turn.", "type": [ "string", "null" ] }, "state": { "$ref": "#/components/schemas/TurnStateRunning" }, "thread_id": { "description": "Thread that owns the event; null for turn-level lifecycle events.", "type": [ "string", "null" ] }, "turn_id": { "description": "Id of the newly created turn.", "type": "string" }, "type": { "description": "Emitted when a turn starts.", "enum": [ "turn.created" ], "type": "string" } }, "required": [ "type", "id", "turn_id", "previous_turn_id", "state", "created_at", "thread_id" ], "type": "object" }, "TurnDoneEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "state": { "description": "Terminal turn state (done, cancelled, or error).", "discriminator": { "mapping": { "cancelled": "#/components/schemas/TurnStateCancelled", "done": "#/components/schemas/TurnStateDone", "error": "#/components/schemas/TurnStateError" }, "propertyName": "status" }, "oneOf": [ { "$ref": "#/components/schemas/TurnStateDone" }, { "$ref": "#/components/schemas/TurnStateCancelled" }, { "$ref": "#/components/schemas/TurnStateError" } ] }, "thread_id": { "description": "Thread that owns the event; null for turn-level lifecycle events.", "type": [ "string", "null" ] }, "type": { "description": "Emitted when a turn reaches a terminal state.", "enum": [ "turn.done" ], "type": "string" } }, "required": [ "type", "id", "state", "created_at", "thread_id" ], "type": "object" }, "TurnMetrics": { "description": "Billable aggregate for this turn so far.", "properties": { "total_cache_read_tokens": { "description": "Total cache-read tokens across model calls in this turn.", "minimum": 0, "type": "integer" }, "total_cache_write_tokens": { "description": "Total cache-write tokens across model calls in this turn.", "minimum": 0, "type": "integer" }, "total_cost_in_usd": { "description": "Estimated total cost in USD for this turn.", "minimum": 0, "type": "number" }, "total_input_tokens": { "description": "Total input tokens across model calls in this turn.", "minimum": 0, "type": "integer" }, "total_output_tokens": { "description": "Total output tokens across model calls in this turn.", "minimum": 0, "type": "integer" }, "total_reasoning_tokens": { "description": "Total reasoning tokens across model calls in this turn.", "minimum": 0, "type": "integer" }, "total_tokens": { "description": "Total tokens (input + output) across model calls in this turn.", "minimum": 0, "type": "integer" } }, "type": "object" }, "TurnState": { "discriminator": { "mapping": { "cancelled": "#/components/schemas/TurnStateCancelled", "done": "#/components/schemas/TurnStateDone", "error": "#/components/schemas/TurnStateError", "paused": "#/components/schemas/TurnStatePaused", "running": "#/components/schemas/TurnStateRunning" }, "propertyName": "status" }, "oneOf": [ { "$ref": "#/components/schemas/TurnStateRunning" }, { "$ref": "#/components/schemas/TurnStatePaused" }, { "$ref": "#/components/schemas/TurnStateDone" }, { "$ref": "#/components/schemas/TurnStateCancelled" }, { "$ref": "#/components/schemas/TurnStateError" } ] }, "TurnStateCancelled": { "properties": { "completed_at": { "description": "ISO 8601 time when cancellation completed.", "type": "string" }, "metrics": { "$ref": "#/components/schemas/TurnMetrics" }, "reason": { "$ref": "#/components/schemas/TurnStateCancelledReason" }, "status": { "description": "Turn was cancelled before completion.", "enum": [ "cancelled" ], "type": "string" } }, "required": [ "status", "reason", "completed_at" ], "type": "object" }, "TurnStateCancelledReason": { "description": "Reason for the cancellation.", "enum": [ "server-execution-timeout", "client-cancelled", "cancelled-for-next-turn", "abandoned" ], "type": "string" }, "TurnStateDone": { "properties": { "completed_at": { "description": "ISO 8601 time when the turn reached a terminal state.", "type": "string" }, "metrics": { "$ref": "#/components/schemas/TurnMetrics" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/ModelMessageEvent" }, { "type": "null" } ], "description": "Final `model.message` for the turn, or null when the turn ended without a final message." }, "required_actions": { "description": "Pending actions (`tool.approval_required`, `tool.response_required`, `mcp.auth_required`); empty when none.", "items": { "$ref": "#/components/schemas/ActionRequiredEvent" }, "type": "array" }, "status": { "description": "Turn finished with no open required actions.", "enum": [ "done" ], "type": "string" } }, "required": [ "status", "output", "required_actions", "completed_at" ], "type": "object" }, "TurnStateError": { "properties": { "completed_at": { "description": "ISO 8601 time when the error state was recorded.", "type": "string" }, "message": { "description": "Human-readable error message.", "type": "string" }, "metrics": { "$ref": "#/components/schemas/TurnMetrics" }, "status": { "description": "Turn ended with an error.", "enum": [ "error" ], "type": "string" } }, "required": [ "status", "message", "completed_at" ], "type": "object" }, "TurnStatePaused": { "properties": { "metrics": { "$ref": "#/components/schemas/TurnMetrics" }, "status": { "description": "Turn is paused waiting for user actions.", "enum": [ "paused" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "TurnStateRunning": { "properties": { "status": { "description": "Turn is still executing.", "enum": [ "running" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "TurnStatus": { "enum": [ "running", "paused", "done", "cancelled", "error" ], "type": "string" }, "TurnStreamingEvent": { "discriminator": { "mapping": { "mcp.auth_required": "#/components/schemas/MCPAuthRequiredEvent", "mcp.initialize": "#/components/schemas/MCPInitializeEvent", "model.message": "#/components/schemas/ModelMessageEvent", "model.message.delta": "#/components/schemas/ModelMessageDeltaEvent", "sandbox.created": "#/components/schemas/SandboxCreatedEvent", "thread.context_compaction_finished": "#/components/schemas/ThreadContextCompactionFinishedEvent", "thread.context_compaction_started": "#/components/schemas/ThreadContextCompactionStartedEvent", "thread.created": "#/components/schemas/ThreadCreatedEvent", "thread.done": "#/components/schemas/ThreadDoneEvent", "tool.approval_required": "#/components/schemas/ToolApprovalRequiredEvent", "tool.response": "#/components/schemas/ToolResponseEvent", "tool.response_required": "#/components/schemas/ToolResponseRequiredEvent", "turn.created": "#/components/schemas/TurnCreatedEvent", "turn.done": "#/components/schemas/TurnDoneEvent", "turn.update": "#/components/schemas/TurnUpdateEvent", "user.mcp_auth_continue": "#/components/schemas/UserMCPAuthContinueEvent", "user.tool_approval": "#/components/schemas/UserToolApprovalEvent", "user.tool_approval_policy": "#/components/schemas/UserToolApprovalPolicyEvent", "user.tool_response": "#/components/schemas/UserToolResponseEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/ModelMessageEvent" }, { "$ref": "#/components/schemas/ModelMessageDeltaEvent" }, { "$ref": "#/components/schemas/ToolResponseEvent" }, { "$ref": "#/components/schemas/ThreadCreatedEvent" }, { "$ref": "#/components/schemas/ThreadDoneEvent" }, { "$ref": "#/components/schemas/ThreadContextCompactionStartedEvent" }, { "$ref": "#/components/schemas/ThreadContextCompactionFinishedEvent" }, { "$ref": "#/components/schemas/MCPAuthRequiredEvent" }, { "$ref": "#/components/schemas/MCPInitializeEvent" }, { "$ref": "#/components/schemas/SandboxCreatedEvent" }, { "$ref": "#/components/schemas/ToolApprovalRequiredEvent" }, { "$ref": "#/components/schemas/ToolResponseRequiredEvent" }, { "$ref": "#/components/schemas/UserToolApprovalEvent" }, { "$ref": "#/components/schemas/UserToolResponseEvent" }, { "$ref": "#/components/schemas/UserToolApprovalPolicyEvent" }, { "$ref": "#/components/schemas/UserMCPAuthContinueEvent" }, { "$ref": "#/components/schemas/TurnCreatedEvent" }, { "$ref": "#/components/schemas/TurnUpdateEvent" }, { "$ref": "#/components/schemas/TurnDoneEvent" } ] }, "TurnUpdateEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "state": { "description": "Live non-terminal turn state (paused or running).", "discriminator": { "mapping": { "paused": "#/components/schemas/TurnStatePaused", "running": "#/components/schemas/TurnStateRunning" }, "propertyName": "status" }, "oneOf": [ { "$ref": "#/components/schemas/TurnStatePaused" }, { "$ref": "#/components/schemas/TurnStateRunning" } ] }, "thread_id": { "description": "Thread that owns the event; null for turn-level lifecycle events.", "type": [ "string", "null" ] }, "type": { "description": "Emitted when a turn pauses or resumes.", "enum": [ "turn.update" ], "type": "string" } }, "required": [ "type", "id", "state", "created_at", "thread_id" ], "type": "object" }, "TurnUserEvent": { "discriminator": { "mapping": { "user.mcp_auth_continue": "#/components/schemas/UserMCPAuthContinueEvent", "user.tool_approval": "#/components/schemas/UserToolApprovalEvent", "user.tool_approval_policy": "#/components/schemas/UserToolApprovalPolicyEvent", "user.tool_response": "#/components/schemas/UserToolResponseEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/UserToolApprovalEvent" }, { "$ref": "#/components/schemas/UserToolResponseEvent" }, { "$ref": "#/components/schemas/UserToolApprovalPolicyEvent" }, { "$ref": "#/components/schemas/UserMCPAuthContinueEvent" } ] }, "TurnUserEventMessage": { "discriminator": { "mapping": { "user.mcp_auth_continue": "#/components/schemas/UserMCPAuthContinueInputEvent", "user.tool_approval": "#/components/schemas/UserToolApprovalInputEvent", "user.tool_approval_policy": "#/components/schemas/UserToolApprovalPolicyMessage", "user.tool_response": "#/components/schemas/UserToolResponseInputEvent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/UserToolApprovalInputEvent" }, { "$ref": "#/components/schemas/UserToolResponseInputEvent" }, { "$ref": "#/components/schemas/UserToolApprovalPolicyMessage" }, { "$ref": "#/components/schemas/UserMCPAuthContinueInputEvent" } ] }, "UpdateAgentRequest": { "additionalProperties": false, "properties": { "description": { "maxLength": 1024, "minLength": 1, "type": "string" }, "manifest": { "$ref": "#/components/schemas/AgentSpec" } }, "required": [ "manifest" ], "type": "object" }, "UpdateConfigurationRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/ConfigurationManifestPatch" } }, "required": [ "manifest" ], "type": "object" }, "UpdateMCPServerRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/MCPServerManifest" } }, "required": [ "manifest" ], "type": "object" }, "UpdateMemoryProviderRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/MemoryProviderManifest" } }, "required": [ "manifest" ], "type": "object" }, "UpdateModelProviderRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/ModelProviderManifest" } }, "required": [ "manifest" ], "type": "object" }, "UpdateSandboxEnvironmentRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/SandboxEnvironmentManifestRequest" } }, "required": [ "manifest" ], "type": "object" }, "UpdateSandboxProviderRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/SandboxProviderManifest" } }, "required": [ "manifest" ], "type": "object" }, "UpdateScheduleRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/ScheduleManifest" }, "name": { "$ref": "#/components/schemas/ResourceName" } }, "required": [ "name", "manifest" ], "type": "object" }, "UpdateSessionGrantsRequest": { "additionalProperties": false, "properties": { "grant": { "default": [], "description": "Subjects to share the session with (up to 50).", "items": { "$ref": "#/components/schemas/SessionGrantSubject" }, "maxItems": 50, "type": "array" }, "revoke": { "default": [], "description": "Subjects to remove access for (up to 50).", "items": { "$ref": "#/components/schemas/SessionGrantSubject" }, "maxItems": 50, "type": "array" } }, "type": "object" }, "UpdateSessionRequest": { "additionalProperties": false, "properties": { "agent": { "$ref": "#/components/schemas/SessionAgentSpecBody" }, "metadata": { "$ref": "#/components/schemas/SessionMetadata" }, "title": { "description": "Human-readable session title.", "maxLength": 50, "minLength": 1, "type": "string" } }, "type": "object" }, "UpdateSkillRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/SkillManifest" } }, "required": [ "manifest" ], "type": "object" }, "UpdateWebSearchProviderRequest": { "additionalProperties": false, "properties": { "manifest": { "$ref": "#/components/schemas/WebSearchProviderManifest" } }, "required": [ "manifest" ], "type": "object" }, "User": { "properties": { "display_name": { "description": "Human-readable name for the user.", "type": "string" }, "email": { "description": "Email of the user.", "type": "string" }, "id": { "description": "User id, unique within the tenant.", "type": "string" } }, "required": [ "id", "display_name", "email" ], "type": "object" }, "UserMCPAuthContinueEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "type": { "description": "Client resume after mcp.auth_required (OAuth completed).", "enum": [ "user.mcp_auth_continue" ], "type": "string" } }, "required": [ "type", "id", "created_at" ], "type": "object" }, "UserMCPAuthContinueInputEvent": { "properties": { "type": { "description": "Client resume after mcp.auth_required (OAuth completed).", "enum": [ "user.mcp_auth_continue" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "UserMessage": { "properties": { "content": { "anyOf": [ { "type": "string" }, { "items": { "$ref": "#/components/schemas/UserMessageContentItem" }, "type": "array" } ], "description": "Plain string or structured text/file content parts." }, "type": { "description": "User message input item.", "enum": [ "user.message" ], "type": "string" } }, "required": [ "type", "content" ], "type": "object" }, "UserMessageContentItem": { "discriminator": { "mapping": { "file": "#/components/schemas/FileContent", "text": "#/components/schemas/TextContent" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/TextContent" }, { "$ref": "#/components/schemas/FileContent" } ] }, "UserToolApprovalEvent": { "properties": { "approval": { "$ref": "#/components/schemas/ApprovalDecision" }, "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "thread_id": { "description": "Thread that owns the pending tool call.", "minLength": 1, "type": "string" }, "tool_call_id": { "description": "Tool call id being approved or denied.", "minLength": 1, "type": "string" }, "type": { "description": "Client resume after tool.approval_required.", "enum": [ "user.tool_approval" ], "type": "string" } }, "required": [ "type", "thread_id", "tool_call_id", "approval", "id", "created_at" ], "type": "object" }, "UserToolApprovalInputEvent": { "properties": { "approval": { "$ref": "#/components/schemas/ApprovalDecision" }, "thread_id": { "description": "Thread that owns the pending tool call.", "minLength": 1, "type": "string" }, "tool_call_id": { "description": "Tool call id being approved or denied.", "minLength": 1, "type": "string" }, "type": { "description": "Client resume after tool.approval_required.", "enum": [ "user.tool_approval" ], "type": "string" } }, "required": [ "type", "thread_id", "tool_call_id", "approval" ], "type": "object" }, "UserToolApprovalPolicyEvent": { "properties": { "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "policies": { "description": "One or more (server_name, name) policy entries.", "items": { "$ref": "#/components/schemas/ToolApprovalPolicyItem" }, "minItems": 1, "type": "array" }, "type": { "description": "Sticky allow-session policy for matching tools (optional expiry).", "enum": [ "user.tool_approval_policy" ], "type": "string" } }, "required": [ "type", "policies", "id", "created_at" ], "type": "object" }, "UserToolApprovalPolicyMessage": { "properties": { "policies": { "description": "One or more (server_name, name) policy entries.", "items": { "$ref": "#/components/schemas/ToolApprovalPolicyItem" }, "minItems": 1, "type": "array" }, "type": { "description": "Sticky allow-session policy for matching tools (optional expiry).", "enum": [ "user.tool_approval_policy" ], "type": "string" } }, "required": [ "type", "policies" ], "type": "object" }, "UserToolResponseEvent": { "properties": { "content": { "description": "Client-side tool result content.", "minLength": 1, "type": "string" }, "created_at": { "description": "ISO 8601 event timestamp.", "type": "string" }, "id": { "description": "Unique identifier for the event (monotonic ULID).", "type": "string" }, "thread_id": { "description": "Thread that owns the pending tool call.", "minLength": 1, "type": "string" }, "tool_call_id": { "description": "Tool call id receiving the client response.", "minLength": 1, "type": "string" }, "type": { "description": "Client resume after tool.response_required.", "enum": [ "user.tool_response" ], "type": "string" } }, "required": [ "type", "thread_id", "tool_call_id", "content", "id", "created_at" ], "type": "object" }, "UserToolResponseInputEvent": { "properties": { "content": { "description": "Client-side tool result content.", "minLength": 1, "type": "string" }, "thread_id": { "description": "Thread that owns the pending tool call.", "minLength": 1, "type": "string" }, "tool_call_id": { "description": "Tool call id receiving the client response.", "minLength": 1, "type": "string" }, "type": { "description": "Client resume after tool.response_required.", "enum": [ "user.tool_response" ], "type": "string" } }, "required": [ "type", "thread_id", "tool_call_id", "content" ], "type": "object" }, "WebSearchCapability": { "properties": { "enabled": { "description": "Whether new chats may use web search: the tenant allows it and a provider is configured.", "type": "boolean" }, "reason": { "description": "Present when web search is unavailable. Explains why.", "type": "string" } }, "required": [ "enabled" ], "type": "object" }, "WebSearchConfig": { "default": { "enabled": false }, "properties": { "enabled": { "default": false, "description": "Enable built-in web search and fetch tools. Default: false (host must configure a provider).", "type": "boolean" } }, "type": "object" }, "WebSearchConfiguration": { "additionalProperties": false, "properties": { "enabled": { "description": "Whether new chats may use web search. Chats that already use it keep their own setting.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" }, "WebSearchProviderManifest": { "oneOf": [ { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ParallelWebSearchProviderAuth" }, "type": { "description": "Parallel web-search provider.", "enum": [ "parallel" ], "type": "string" } }, "required": [ "type", "auth" ], "type": "object" } ] }, "ZaiModelProvider": { "additionalProperties": false, "properties": { "auth": { "$ref": "#/components/schemas/ModelProviderAuth" }, "base_url": { "default": "https://api.z.ai/api/paas/v4", "description": "Override of the provider's default API base URL.", "format": "uri", "type": "string" }, "models": { "description": "Models exposed by this provider (at least one).", "items": { "$ref": "#/components/schemas/ConfiguredModel" }, "minItems": 1, "type": "array" }, "type": { "enum": [ "zai" ], "type": "string" } }, "required": [ "auth", "models", "type" ], "type": "object" }, "ZepMemoryProviderAuth": { "additionalProperties": false, "description": "Zep authentication credentials.", "properties": { "api_key": { "description": "Zep API key. Responses are redacted; on PUT, a real value sets/rotates and a redacted value keeps the stored key.", "minLength": 1, "type": "string" } }, "required": [ "api_key" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "bearerFormat": "JWT", "description": "Caller credential (`Authorization: Bearer `). Required on protected routes when auth is enabled. Browser sessions may use the HttpOnly `id_token` or `accessToken` cookie instead.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are served at `/api/v1/docs` (OpenAPI JSON at `/api/v1/openapi.json`).\n\n**Authentication:** Standalone auth accepts requests without credentials — middleware stamps a local default user. When OIDC or TrueFoundry auth is configured, protected routes require a valid cookie or `Authorization: Bearer` token. There is no built-in API-key scheme; pass custom headers only if your reverse proxy or IdP layer requires them.\n\nCovers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.", "title": "TrueForge API", "version": "0.0.0" }, "openapi": "3.1.0", "paths": { "/api/internal/list-permissions": { "post": { "description": "Return granted actions for the requested resources.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPermissionsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPermissionsResponse" } } }, "description": "Permissions envelope: `{ type, permissions }`." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid Bearer token or auth cookie" } }, "summary": "List permissions for resources", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal" ], "x-fern-sdk-method-name": "list_permissions" } }, "/api/internal/metrics/charts": { "get": { "description": "List available session metric charts.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionMetricsChartResponse" } } }, "description": "Available session metric charts." } }, "summary": "Get session metrics charts", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "metrics" ], "x-fern-sdk-method-name": "list_charts" } }, "/api/internal/metrics/charts-data": { "get": { "description": "Return one chart for the caller's sessions on a named agent over an inclusive creation-time window. Uses hourly buckets for windows up to 24 hours and daily UTC buckets otherwise.", "parameters": [ { "description": "Named agent identifier.", "in": "query", "name": "agent_id", "required": true, "schema": { "description": "Named agent identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Inclusive lower bound on session `created_at`.", "in": "query", "name": "start_timestamp", "required": true, "schema": { "description": "Inclusive lower bound on session `created_at`.", "format": "date-time", "type": "string" } }, { "description": "Inclusive upper bound on session `created_at`.", "in": "query", "name": "end_timestamp", "required": true, "schema": { "description": "Inclusive upper bound on session `created_at`.", "format": "date-time", "type": "string" } }, { "description": "Session metrics chart to return.", "in": "query", "name": "chart_name", "required": true, "schema": { "$ref": "#/components/schemas/SessionMetricsChartName" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionMetricsChartDataResponse" } } }, "description": "Zero-filled time series for one chart." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid timestamps or a window longer than 30 days." } }, "summary": "Get session metrics chart data", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "metrics" ], "x-fern-sdk-method-name": "get_chart_data" } }, "/api/internal/metrics/meters": { "get": { "description": "Aggregate the caller's session meters for a named agent over an inclusive creation-time window.", "parameters": [ { "description": "Named agent identifier.", "in": "query", "name": "agent_id", "required": true, "schema": { "description": "Named agent identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Inclusive lower bound on session `created_at`.", "in": "query", "name": "start_timestamp", "required": true, "schema": { "description": "Inclusive lower bound on session `created_at`.", "format": "date-time", "type": "string" } }, { "description": "Inclusive upper bound on session `created_at`.", "in": "query", "name": "end_timestamp", "required": true, "schema": { "description": "Inclusive upper bound on session `created_at`.", "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionMetricsMeterResponse" } } }, "description": "Session metric meters." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid timestamps or a window longer than 30 days." } }, "summary": "Get session metrics meters", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "metrics" ], "x-fern-sdk-method-name": "get_meters" } }, "/api/internal/sandbox-environments/pending": { "get": { "description": "Returns pending environment versions for the build controller.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPendingSandboxEnvironmentVersionsResponse" } } }, "description": "Pending versions oldest-first." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid service credential." } }, "summary": "List pending sandbox environment versions", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "sandbox_environments" ], "x-fern-sdk-method-name": "list_pending" } }, "/api/internal/sandbox-environments/progress": { "post": { "description": "Registers or polls the snapshot build and updates version status.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgressSandboxEnvironmentVersionRequest" } } }, "required": true }, "responses": { "204": { "description": "Progressed (or left pending)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid service credential." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Version not found." } }, "summary": "Progress a pending sandbox environment version", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "sandbox_environments" ], "x-fern-sdk-method-name": "progress" } }, "/api/internal/schedules/runs/execute": { "post": { "description": "Execute a persisted schedule run using its saved schedule and agent.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteScheduleRunRequest" } } }, "required": true }, "responses": { "204": { "description": "Run executed or already has a turn." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid service credential." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Run, schedule, or agent not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The run cannot be executed." } }, "summary": "Execute a schedule run", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "schedules" ], "x-fern-sdk-method-name": "execute_run" } }, "/api/internal/sessions/get-or-create-by-external-id": { "post": { "description": "Idempotent get-or-create: returns the existing session for this `external_id`, or creates one", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrCreateSessionByExternalIdRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } }, "description": "Session already existed for this external id." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } }, "description": "Session created." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller is not the session creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Named agent not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox)." } }, "summary": "Get or create a session by external id", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "sessions" ], "x-fern-sdk-method-name": "get_or_create_by_external_id" } }, "/api/internal/sessions/{session_id}/turns": { "post": { "description": "Service API key. Non-streaming; requires external_id and a non-null source.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalCreateSessionTurnRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTurnResponse" } } }, "description": "The running turn." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid service credential." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session lacks external_id or source and is not eligible." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session, prior turn, or referenced agent not found." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Requested action cannot be performed on the session because it is no longer usable." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Request body exceeds the configured maximum size (MAX_REQUEST_BODY_BYTES)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Missing agent/resource, sandbox unavailable, or turn input conflicts with session state." } }, "summary": "Create and execute a turn in a session (internal)", "tags": [ "Internal" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "sessions" ], "x-fern-sdk-method-name": "create_turn" } }, "/api/v1/agents": { "get": { "description": "List configured agents for the tenant, ordered by name. Optional `agent_name` filters by substring.", "parameters": [ { "description": "Page size. Defaults to 50, max 100.", "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "description": "Page size. Defaults to 50, max 100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque token from a previous response `next_page_token`.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Opaque token from a previous response `next_page_token`.", "type": "string" } }, { "description": "Case-insensitive substring match on agent name.", "in": "query", "name": "agent_name", "required": false, "schema": { "description": "Case-insensitive substring match on agent name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" } } }, "description": "Paginated matching agents." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid query parameters or page token." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." } }, "summary": "List agents", "tags": [ "Agents" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "list", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "Discover existing agents — for example to find one to inspect or update, or to check whether a name is already taken before creating a new agent. Supports optional filters and returns one paginated page.", "name": "list_agents" } }, "post": { "description": "Creates an agent and allocates an immutable id. Fails if `name` is already taken. Name cannot be changed later.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } } }, "description": "The created agent." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body or unknown model/MCP/skill refs." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "An agent with this name already exists." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The agent spec is valid but requires a capability this server does not provide (e.g. sandbox or skills)." } }, "summary": "Create an agent", "tags": [ "Agents" ], "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "create", "x-tfg-mcp": { "annotations": { "destructiveHint": false, "idempotentHint": false, "readOnlyHint": false }, "description": "Create a named agent from a complete manifest. The name is immutable and all referenced models, MCP servers, skills, and sandbox environments must exist.", "name": "create_agent" } } }, "/api/v1/agents/{agent_id}": { "delete": { "description": "Delete a configured agent by immutable id.", "parameters": [ { "description": "Immutable agent identifier.", "in": "path", "name": "agent_id", "required": true, "schema": { "description": "Immutable agent identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAgentResponse" } } }, "description": "Agent deleted." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Agent not found." } }, "summary": "Delete an agent", "tags": [ "Agents" ], "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "delete" }, "get": { "description": "Fetch a configured agent by immutable id.", "parameters": [ { "description": "Immutable agent identifier.", "in": "path", "name": "agent_id", "required": true, "schema": { "description": "Immutable agent identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } } }, "description": "The agent." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Agent not found." } }, "summary": "Get an agent", "tags": [ "Agents" ], "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "get", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "Fetch one agent's full definition by its immutable ID, including the complete manifest. Use it to review an agent or to get a working template before updating it.", "name": "get_agent" } }, "put": { "description": "Update an existing agent by immutable id.", "parameters": [ { "description": "Immutable agent identifier.", "in": "path", "name": "agent_id", "required": true, "schema": { "description": "Immutable agent identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentResponse" } } }, "description": "The saved agent." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body or unknown model/MCP/skill refs." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Agent not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The agent spec is valid but requires a capability this server does not provide (e.g. sandbox or skills)." } }, "summary": "Update an agent", "tags": [ "Agents" ], "x-fern-sdk-group-name": [ "agents" ], "x-fern-sdk-method-name": "update", "x-tfg-mcp": { "annotations": { "destructiveHint": true, "idempotentHint": true, "readOnlyHint": false }, "description": "Replace an agent's description and complete manifest by immutable ID. This is a full replacement: omitted manifest fields are removed. Call get_agent first to retrieve the current complete manifest and edit it as a template rather than authoring one from scratch.", "name": "update_agent" } } }, "/api/v1/agents/{agent_id}/code-snippets": { "get": { "description": "TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.", "parameters": [ { "description": "Immutable agent identifier.", "in": "path", "name": "agent_id", "required": true, "schema": { "description": "Immutable agent identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL.", "in": "query", "name": "base_url", "required": false, "schema": { "description": "Public SDK base URL from the browser. When omitted, derived from the request origin and PUBLIC_BASE_URL.", "format": "uri", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentCodeSnippetsResponse" } } }, "description": "SDK samples." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Agent not found." } }, "summary": "Get agent SDK code snippets", "tags": [ "Agents" ], "x-excluded": true, "x-fern-sdk-group-name": [ "internal", "agents" ], "x-fern-sdk-method-name": "get_code_snippets" } }, "/api/v1/auth/callback": { "get": { "description": "Browser-redirect target hit by the identity provider after login, never called directly by SDK consumers. In local/single-binary mode, redirects straight back into the app.", "parameters": [ { "description": "Authorization code, present when the user granted consent.", "in": "query", "name": "code", "required": false, "schema": { "description": "Authorization code, present when the user granted consent.", "minLength": 1, "type": "string" } }, { "description": "Opaque token; correlates this callback to its pending login. Always present, success or error.", "in": "query", "name": "state", "required": true, "schema": { "description": "Opaque token; correlates this callback to its pending login. Always present, success or error.", "minLength": 1, "type": "string" } }, { "description": "Error code from the identity provider, present instead of `code` if the user denied consent.", "in": "query", "name": "error", "required": false, "schema": { "description": "Error code from the identity provider, present instead of `code` if the user denied consent.", "type": "string" } }, { "description": "Human-readable error detail from the identity provider when `error` is set.", "in": "query", "name": "error_description", "required": false, "schema": { "description": "Human-readable error detail from the identity provider when `error` is set.", "type": "string" } } ], "responses": { "302": { "description": "Redirect back into the app on success, or to /?error= on failure." } }, "summary": "Login callback", "tags": [ "Auth" ], "x-excluded": true, "x-fern-ignore": true } }, "/api/v1/auth/login": { "get": { "description": "Redirects the browser to begin authentication. Optional `return_to` is the same-origin path to land on afterward.", "parameters": [ { "description": "Same-origin path to land on after authentication.", "in": "query", "name": "return_to", "required": false, "schema": { "description": "Same-origin path to land on after authentication.", "type": "string" } } ], "responses": { "302": { "description": "Redirect to continue authentication." } }, "summary": "Start the login flow", "tags": [ "Auth" ], "x-excluded": true, "x-fern-ignore": true } }, "/api/v1/auth/logout": { "post": { "description": "Ends the local harness session only — does not hit the IdP end-session endpoint. A no-op in local/single-binary mode, since there is no real session to clear.", "responses": { "204": { "description": "Session cookie cleared." } }, "summary": "Clear the local session", "tags": [ "Auth" ], "x-excluded": true, "x-fern-ignore": true } }, "/api/v1/auth/me": { "get": { "description": "Returns the authenticated caller identity (`type`, `tenant_id`, `subject`, `roles`) wrapped as `{ data }`. `type` is `oidc-connected` when browser OIDC is enabled, otherwise `default`. When auth is enabled this requires a valid `id_token` cookie or `Authorization: Bearer` token (401 otherwise). When auth is disabled, returns the standalone default identity.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMeResponse" } } }, "description": "Caller identity for the current request." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Auth is enabled and the request has no valid cookie or Bearer token." } }, "summary": "Current session", "tags": [ "Auth" ], "x-fern-sdk-group-name": [ "auth" ], "x-fern-sdk-method-name": "me" } }, "/api/v1/capabilities": { "get": { "description": "Report optional runtime capabilities available for this tenant.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCapabilitiesResponse" } } }, "description": "Server capabilities." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." } }, "summary": "Get server capabilities", "tags": [ "Capabilities" ], "x-fern-sdk-group-name": [ "server" ], "x-fern-sdk-method-name": "get_capabilities" } }, "/api/v1/catalogs/mcp-servers": { "get": { "description": "Shipped MCP server presets (discovery-only). Copy into PUT /settings/mcp-servers to configure.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMCPServerCatalogResponse" } } }, "description": "Shipped MCP server presets." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not authenticated." } }, "summary": "Get the MCP catalog", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "catalogs", "mcpServers" ], "x-fern-sdk-method-name": "list" } }, "/api/v1/catalogs/memory-providers": { "get": { "description": "Shipped memory provider presets.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMemoryProviderCatalogResponse" } } }, "description": "Shipped memory provider presets." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not authenticated." } }, "summary": "List memory providers", "tags": [ "Memory Providers" ], "x-fern-sdk-group-name": [ "catalogs", "memoryProviders" ], "x-fern-sdk-method-name": "list" } }, "/api/v1/catalogs/model-providers": { "get": { "description": "Shipped model-provider presets (discovery-only). Copy into PUT /settings/model-providers to configure. Includes a `custom` sentinel with `supported_reasoning_efforts`.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetModelProviderCatalogResponse" } } }, "description": "Shipped model-provider presets." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not authenticated." } }, "summary": "Get the model catalog", "tags": [ "Models" ], "x-fern-sdk-group-name": [ "catalogs", "modelProviders" ], "x-fern-sdk-method-name": "list" } }, "/api/v1/catalogs/sandbox-providers": { "get": { "description": "Shipped sandbox-provider presets (discovery-only). Copy into PUT /settings/sandbox-providers to configure.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSandboxProviderCatalogResponse" } } }, "description": "Shipped sandbox-provider presets." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not authenticated." } }, "summary": "Get the sandbox provider catalog", "tags": [ "Sandboxes" ], "x-fern-sdk-group-name": [ "catalogs", "sandboxProviders" ], "x-fern-sdk-method-name": "list" } }, "/api/v1/catalogs/skills": { "get": { "description": "Shipped skill presets (discovery-only). Copy into PUT /settings/skills to configure.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSkillCatalogResponse" } } }, "description": "Shipped skill presets." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not authenticated." } }, "summary": "Get the skill catalog", "tags": [ "Skills" ], "x-fern-sdk-group-name": [ "catalogs", "skills" ], "x-fern-sdk-method-name": "list" } }, "/api/v1/catalogs/web-search-providers": { "get": { "description": "Shipped web-search provider presets.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebSearchProviderCatalogResponse" } } }, "description": "Shipped web-search provider presets." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not authenticated." } }, "summary": "List web search providers", "tags": [ "Web Search Providers" ], "x-fern-sdk-group-name": [ "catalogs", "webSearchProviders" ], "x-fern-sdk-method-name": "list" } }, "/api/v1/mcp-servers": { "get": { "description": "Configured MCP servers as a slim name/url list for the composer.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAvailableMCPServersResponse" } } }, "description": "All configured MCP servers (chat projection)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." } }, "summary": "List MCP servers for chat", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "mcpServers" ], "x-fern-sdk-method-name": "list", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "List the MCP servers you can attach to an agent, each with its current authentication status so you know whether it is ready to use. Check this before referencing an MCP server in a manifest.", "name": "list_mcp_servers" } } }, "/api/v1/mcp-servers/oauth/callback": { "get": { "description": "Browser redirect target for MCP server OAuth. The authorization server redirects here with `code`/`state` (or `error`). Exchanges the code for tokens, then either returns JSON or redirects to the `return_to` path supplied at authorize time. Not called by the SDK — browsers hit this URL directly.", "parameters": [ { "description": "Authorization code, present when the user granted consent.", "in": "query", "name": "code", "required": false, "schema": { "description": "Authorization code, present when the user granted consent.", "minLength": 1, "type": "string" } }, { "description": "Opaque token; correlates this callback to its pending login. Always present, success or error.", "in": "query", "name": "state", "required": true, "schema": { "description": "Opaque token; correlates this callback to its pending login. Always present, success or error.", "minLength": 1, "type": "string" } }, { "description": "Error code from the identity provider, present instead of `code` if the user denied consent.", "in": "query", "name": "error", "required": false, "schema": { "description": "Error code from the identity provider, present instead of `code` if the user denied consent.", "type": "string" } }, { "description": "Human-readable error detail from the identity provider when `error` is set.", "in": "query", "name": "error_description", "required": false, "schema": { "description": "Human-readable error detail from the identity provider when `error` is set.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "description": "Present when the OAuth callback completed without a return_to.", "enum": [ true ], "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Token exchanged successfully and no `return_to` was given at authorize time." }, "302": { "description": "Redirect to the `return_to` path given at authorize time, with `isSuccess` (and `reason` when it failed) appended to its existing query params." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "IdP `error`, unknown/expired `state`, token exchange failure, or `code`/`error` both missing." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unexpected failure during token exchange." } }, "summary": "OAuth callback for MCP authorization", "tags": [ "MCP Servers" ], "x-excluded": true, "x-fern-ignore": true } }, "/api/v1/mcp-servers/{name}": { "get": { "description": "A single MCP server as the slim chat projection, with live per-user auth_status.", "parameters": [ { "description": "MCP server name.", "in": "path", "name": "name", "required": true, "schema": { "description": "MCP server name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAvailableMCPServerResponse" } } }, "description": "The MCP server (chat projection)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "MCP server not found." } }, "summary": "Get an MCP server for chat", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "mcpServers" ], "x-fern-sdk-method-name": "get", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "Fetch one MCP server by name — its public connection details and current authentication status — to confirm it exists and is authenticated before referencing it in an agent.", "name": "get_mcp_server" } } }, "/api/v1/mcp-servers/{name}/authorize": { "delete": { "description": "Disconnects OAuth for the MCP server when applicable and returns the updated server with auth_status. No-op when the server does not use stored OAuth tokens.", "parameters": [ { "description": "MCP server name.", "in": "path", "name": "name", "required": true, "schema": { "description": "MCP server name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMCPServerResponse" } } }, "description": "The MCP server after disconnect." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "MCP server not found." } }, "summary": "Disconnect OAuth for an MCP server", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "mcpServers" ], "x-fern-sdk-method-name": "delete_authorization" }, "get": { "description": "Returns current auth status. When OAuth is required, includes an authorization URL. Optional return_to is the post-consent landing path.", "parameters": [ { "description": "MCP server name.", "in": "path", "name": "name", "required": true, "schema": { "description": "MCP server name.", "minLength": 1, "type": "string" } }, { "description": "Same-origin path to land in the browser after consent. When omitted, no post-consent redirect is requested.", "in": "query", "name": "return_to", "required": false, "schema": { "description": "Same-origin path to land in the browser after consent. When omitted, no post-consent redirect is requested.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPAuthStatus" } } }, "description": "Either already authenticated, or an authorization URL to redirect to." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid return_to." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "MCP server not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "DCR could not be completed for this server (e.g. it lacks a registration_endpoint)." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The authorization server failed dynamic client registration or authorization startup." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Server misconfiguration (e.g. PUBLIC_BASE_URL unset)." } }, "summary": "Start (or short-circuit) the auth flow for an MCP server", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "mcpServers" ], "x-fern-sdk-method-name": "authorize" } }, "/api/v1/mcp-servers/{name}/tools": { "get": { "description": "All tools exposed by the given MCP server (non-paginated), as returned by the MCP `tools/list` call.", "parameters": [ { "description": "MCP server name.", "in": "path", "name": "name", "required": true, "schema": { "description": "MCP server name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMCPServerToolsResponse" } } }, "description": "All tools of the MCP server." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "MCP server not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The MCP server requires authentication (does not trigger browser OIDC login)." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The MCP server could not be reached or returned an error." } }, "summary": "List tools of an MCP server", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "mcpServers" ], "x-fern-sdk-method-name": "list_tools" } }, "/api/v1/models": { "get": { "description": "Configured models as a slim FQN list for the composer.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAvailableModelsResponse" } } }, "description": "All configured models (chat projection)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Auth is configured and the request has no valid no Bearer token or session cookie." } }, "summary": "List models for chat", "tags": [ "Models" ], "x-fern-sdk-group-name": [ "models" ], "x-fern-sdk-method-name": "list", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "List the models you can reference in an agent or draft manifest. Use it to find a valid model identifier before setting one on an agent.", "name": "list_models" } } }, "/api/v1/sandbox-environments": { "get": { "description": "List available sandbox environments", "parameters": [ { "description": "Page size. Defaults to 25, max 1000.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "description": "Page size. Defaults to 25, max 1000.", "maximum": 1000, "minimum": 1, "type": "integer" } }, { "description": "Opaque token from a previous response `next_page_token`.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Opaque token from a previous response `next_page_token`.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSandboxEnvironmentsResponse" } } }, "description": "Paginated sandbox environments." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid query parameters or page token." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unauthenticated." } }, "summary": "List sandbox environments", "tags": [ "Sandboxes" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "sandboxEnvironments" ], "x-fern-sdk-method-name": "list", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "Discover existing sandbox environments you can reference from an agent, or find one to update. Returns one paginated page. Secret values are redacted; never ask the user for them. When an environment needs secrets, ask the user to create them in the sandbox environment settings.", "name": "list_sandbox_environments" } }, "post": { "description": "Creates by `manifest.name`. Fails if the name is already taken. Requires a configured sandbox provider.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxEnvironmentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSandboxEnvironmentResponse" } } }, "description": "The created sandbox environment." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, resource allocation, or missing secret value." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unauthenticated." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "User does not have permission to edit Sandbox environment" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "A sandbox environment with this name already exists." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox provider is missing, credentials are invalid, or rejected the secret." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox provider secret synchronization failed." } }, "summary": "Create a sandbox environment", "tags": [ "Sandboxes" ], "x-fern-sdk-group-name": [ "sandboxEnvironments" ], "x-fern-sdk-method-name": "create", "x-tfg-mcp": { "annotations": { "destructiveHint": false, "idempotentHint": false, "readOnlyHint": false }, "description": "Create a reusable sandbox environment that agents run in — defining its resources, environment variables, networking, and build configuration — from a complete manifest. Fails if an environment with the same name already exists; the reserved `default` environment cannot be created. Never ask the user for a secret value and never send networking.secrets. When the environment needs secrets, ask the user to create them in the sandbox environment settings.", "name": "create_sandbox_environment" } }, "put": { "description": "Create a new sandbox environment or update an existing one.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSandboxEnvironmentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSandboxEnvironmentResponse" } } }, "description": "The saved sandbox environment." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, resource allocation, or missing secret value." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unauthenticated." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "User does not have permission to edit Sandbox environment" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox environment not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Name conflict or concurrent update." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox provider is missing, credentials are invalid, or rejected the secret." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox provider secret synchronization failed." } }, "summary": "Create or update a sandbox environment", "tags": [ "Sandboxes" ], "x-fern-sdk-group-name": [ "sandboxEnvironments" ], "x-fern-sdk-method-name": "create_or_update" } }, "/api/v1/sandbox-environments/{name}": { "delete": { "description": "Delete a sandbox environment. Fails if any agent still references it, if it is the tenant default, or if it is the reserved platform environment.", "parameters": [ { "description": "Sandbox environment name.", "in": "path", "name": "name", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ResourceName" }, { "description": "Sandbox environment name." } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSandboxEnvironmentResponse" } } }, "description": "Sandbox environment deleted, or already absent." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unauthenticated." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "User does not have permission to edit Sandbox environment" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Environment is referenced by an agent, is the tenant default, or is reserved by the platform." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox provider is missing, credentials are invalid, or rejected secret deletion." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox provider secret deletion failed." } }, "summary": "Delete a sandbox environment", "tags": [ "Sandboxes" ], "x-fern-sdk-group-name": [ "sandboxEnvironments" ], "x-fern-sdk-method-name": "delete" }, "get": { "parameters": [ { "description": "Sandbox environment name.", "in": "path", "name": "name", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ResourceName" }, { "description": "Sandbox environment name." } ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSandboxEnvironmentResponse" } } }, "description": "The sandbox environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unauthenticated." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox environment not found." } }, "summary": "Get a sandbox environment", "tags": [ "Sandboxes" ], "x-fern-sdk-group-name": [ "sandboxEnvironments" ], "x-fern-sdk-method-name": "get", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "Fetch one sandbox environment by name — its manifest, build status, resources, environment variables, and networking configuration. Use it to review an environment or get a template before updating it. Secret values are redacted; never ask the user for them. When the environment needs secrets, ask the user to create them in the sandbox environment settings.", "name": "get_sandbox_environment" } }, "patch": { "description": "Update sandbox environment metadata.", "parameters": [ { "description": "Sandbox environment name.", "in": "path", "name": "name", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/ResourceName" }, { "description": "Sandbox environment name." } ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchSandboxEnvironmentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSandboxEnvironmentResponse" } } }, "description": "The updated sandbox environment." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unauthenticated." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "User cannot edit this environment." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox environment not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Environment is disabled when setting default, or the default changed concurrently." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox provider is missing or does not support environments." } }, "summary": "Update sandbox environment flags", "tags": [ "Sandboxes" ], "x-fern-sdk-group-name": [ "sandboxEnvironments" ], "x-fern-sdk-method-name": "update" } }, "/api/v1/schedules": { "get": { "description": "List schedules for the tenant, newest first.", "parameters": [ { "description": "Page size. Defaults to 25", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "description": "Page size. Defaults to 25", "maximum": 25, "minimum": 1, "type": "integer" } }, { "description": "Opaque token from a previous response `next_page_token`.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Opaque token from a previous response `next_page_token`.", "type": "string" } }, { "description": "Filter by one or more agent names (comma-separated). When set, at least one name is required.", "in": "query", "name": "agent_names", "required": false, "schema": { "description": "Filter by one or more agent names (comma-separated). When set, at least one name is required.", "type": "string" } }, { "description": "When true, only schedules created by the authenticated subject.", "in": "query", "name": "created_by_me", "required": false, "schema": { "description": "When true, only schedules created by the authenticated subject.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSchedulesResponse" } } }, "description": "Paginated matching schedules." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid query parameters or page token." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unauthenticated." } }, "summary": "List schedules", "tags": [ "Schedules" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "schedules" ], "x-fern-sdk-method-name": "list", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "Discover existing schedules — for example to see what an agent already runs on a timer, or to find one to update. Supports optional filters and returns one paginated page.", "name": "list_schedules" } }, "post": { "description": "Create a schedule for an existing agent (by name) and add its first pending run when active.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetScheduleResponse" } } }, "description": "Created schedule." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid cron or timezone." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Named agent not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The name is already taken for this agent, or the schedule was modified concurrently (retry)." } }, "summary": "Create a schedule", "tags": [ "Schedules" ], "x-fern-sdk-group-name": [ "schedules" ], "x-fern-sdk-method-name": "create", "x-tfg-mcp": { "annotations": { "destructiveHint": false, "idempotentHint": false, "readOnlyHint": false }, "description": "Make an existing named agent run automatically on a recurring basis — for example a daily summary — by binding it to a task and a cron schedule. Timezone defaults to UTC and status to active.", "name": "create_schedule" } } }, "/api/v1/schedules/runs": { "post": { "description": "Start a schedule run immediately using the schedule task. Does not replace or advance the cron pending run.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRunRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduleRunResponse" } } }, "description": "Run created." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request or turn input." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The caller is not the schedule creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Schedule or agent not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Run name conflict (retry)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The run cannot be started (e.g. agent resources unavailable)." } }, "summary": "Trigger a schedule run", "tags": [ "Schedules" ], "x-fern-sdk-group-name": [ "schedules" ], "x-fern-sdk-method-name": "create_run" } }, "/api/v1/schedules/{schedule_id}": { "delete": { "description": "Delete a schedule and its runs. Idempotent.", "parameters": [ { "description": "Immutable schedule identifier.", "in": "path", "name": "schedule_id", "required": true, "schema": { "description": "Immutable schedule identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteScheduleResponse" } } }, "description": "Deleted." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unauthenticated." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The caller is not the schedule creator." } }, "summary": "Delete a schedule", "tags": [ "Schedules" ], "x-fern-sdk-group-name": [ "schedules" ], "x-fern-sdk-method-name": "delete" }, "get": { "description": "Get a schedule by id.", "parameters": [ { "description": "Immutable schedule identifier.", "in": "path", "name": "schedule_id", "required": true, "schema": { "description": "Immutable schedule identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetScheduleResponse" } } }, "description": "The schedule." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The caller is not the schedule creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not found." } }, "summary": "Get a schedule", "tags": [ "Schedules" ], "x-fern-sdk-group-name": [ "schedules" ], "x-fern-sdk-method-name": "get", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "Fetch one schedule's full configuration by its immutable ID — its bound agent, task, cron expression, timezone, and status. Use it to review a schedule or get a template before updating it.", "name": "get_schedule" } }, "put": { "description": "Replace name and manifest; replaces or drops the pending run when status/cron/timezone change.", "parameters": [ { "description": "Immutable schedule identifier.", "in": "path", "name": "schedule_id", "required": true, "schema": { "description": "Immutable schedule identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetScheduleResponse" } } }, "description": "Updated schedule." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid cron." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The caller is not the schedule creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The name is already taken for this agent, or the schedule was modified concurrently (retry)." } }, "summary": "Update a schedule", "tags": [ "Schedules" ], "x-fern-sdk-group-name": [ "schedules" ], "x-fern-sdk-method-name": "update", "x-tfg-mcp": { "annotations": { "destructiveHint": true, "idempotentHint": true, "readOnlyHint": false }, "description": "Change an existing schedule — for example its task, cadence, or active/paused state — by replacing its name and complete manifest by immutable ID. The bound agent cannot change, and because this is a full replacement, omitted optional fields return to their defaults.", "name": "update_schedule" } } }, "/api/v1/schedules/{schedule_id}/runs": { "get": { "description": "List runs of a schedule, newest `scheduled_for` first. Available to its creator or a manager of its agent.", "parameters": [ { "description": "Immutable schedule identifier.", "in": "path", "name": "schedule_id", "required": true, "schema": { "description": "Immutable schedule identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Page size. Defaults to 25", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "description": "Page size. Defaults to 25", "maximum": 25, "minimum": 1, "type": "integer" } }, { "description": "Opaque token from a previous response `next_page_token`.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Opaque token from a previous response `next_page_token`.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScheduleRunsResponse" } } }, "description": "Paginated runs of the schedule." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid query parameters or page token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The caller cannot read the schedule." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Not found." } }, "summary": "List runs of a schedule", "tags": [ "Schedules" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "schedules" ], "x-fern-sdk-method-name": "list_runs", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "Check a schedule's execution history to see whether its runs are succeeding or why they failed. Each run includes its status, scheduled and triggered times, and any failure reason. Returns one paginated page.", "name": "list_schedule_runs" } } }, "/api/v1/sessions": { "get": { "description": "List the sessions (newest first by default).", "parameters": [ { "description": "Page size. Defaults to 25, max 25.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "description": "Page size. Defaults to 25, max 25.", "maximum": 25, "minimum": 1, "type": "integer" } }, { "description": "Sort sessions by `updated_at`. Defaults to \"desc\".", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListSessionsOrder" } }, { "description": "Opaque keyset cursor from a previous response `next_page_token`.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Opaque keyset cursor from a previous response `next_page_token`.", "minLength": 1, "type": "string" } }, { "description": "Inclusive lower bound on `created_at` (ISO-8601 / RFC 3339).", "in": "query", "name": "start_timestamp", "required": false, "schema": { "description": "Inclusive lower bound on `created_at` (ISO-8601 / RFC 3339).", "format": "date-time", "type": "string" } }, { "description": "Inclusive upper bound on `created_at` (ISO-8601 / RFC 3339).", "in": "query", "name": "end_timestamp", "required": false, "schema": { "description": "Inclusive upper bound on `created_at` (ISO-8601 / RFC 3339).", "format": "date-time", "type": "string" } }, { "description": "When set, only sessions bound to this agent id are returned.", "in": "query", "name": "agent_id", "required": false, "schema": { "description": "When set, only sessions bound to this agent id are returned.", "minLength": 1, "type": "string" } }, { "description": "When true, only sessions created by the authenticated subject.", "in": "query", "name": "created_by_me", "required": false, "schema": { "description": "When true, only sessions created by the authenticated subject.", "type": "boolean" } }, { "description": "Exact metadata pairs as metadata[key]=value. Sessions must contain all pairs.", "explode": true, "in": "query", "name": "metadata", "required": false, "schema": { "$ref": "#/components/schemas/SessionMetadata" }, "style": "deepObject" }, { "description": "When set, returns only sessions created by this source type.", "in": "query", "name": "source_type", "required": false, "schema": { "$ref": "#/components/schemas/SessionSourceType" } }, { "description": "When set, returns only sessions from this specific source. Requires source_type.", "in": "query", "name": "source_id", "required": false, "schema": { "description": "When set, returns only sessions from this specific source. Requires source_type.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionsResponse" } } }, "description": "Paginated sessions." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid query parameters or page token." } }, "summary": "List sessions", "tags": [ "Agent Sessions" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "list" }, "post": { "description": "Create a session with `agent` as either `{ name }` (named registry binding) or `{ spec: AgentSpec }` (inline). Named sessions snapshot the agent name at create and resolve the live agent on each turn. Responses use `{ type: \"reference\", name, id }` or `{ type: \"inline\", spec }`.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } }, "description": "Session created." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Named agent not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The agent spec is valid but references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox)." } }, "summary": "Create a session", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "create" } }, "/api/v1/sessions/{session_id}": { "delete": { "description": "Delete a session and all related turns, events, and internal state. Only the session creator may delete it. Idempotent if already gone.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "204": { "description": "Session and all related data deleted." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller is not the session creator." } }, "summary": "Delete a session", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "delete" }, "get": { "description": "Fetch a session by ID. Allowed for the creator, a manager of the bound named agent, or a subject with a session access grant.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } }, "description": "Session data." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller cannot read this session." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session not found." } }, "summary": "Get a session", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "get" }, "patch": { "description": "Update a session: optional `title`, `metadata`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSessionResponse" } } }, "description": "Session updated." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller is not the session creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Named session rejected an agent update, or the agent spec references a resource this server does not provide (e.g. model, MCP server, skill, or sandbox)." } }, "summary": "Update a session", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "update" } }, "/api/v1/sessions/{session_id}/cancel": { "post": { "description": "Cancel the running last turn for a session. Only the session creator may cancel.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSessionRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSessionResponse" } } }, "description": "Turn cancelled." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller is not the session creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session not found." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Requested action cannot be performed on the session because it is no longer usable, or the executor owning the running turn is unreachable." } }, "summary": "Cancel a running turn in a session", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "cancel" } }, "/api/v1/sessions/{session_id}/events": { "get": { "description": "List session events as `{ turn_id, event }` across the active turn branch (newest first), including persisted events from a running tip. Each turn contributes turn.created, content events (model.message, tool.call, …), and turn.done when terminal; streaming deltas are not included. Use `page_token` to paginate backward toward older events while retaining the original branch anchor. Allowed for the creator, a manager of the bound named agent, or a subject with a session access grant.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Pagination cursor from `pagination.next_page_token`. It retains the branch anchor turn and returns older events toward the session start.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Pagination cursor from `pagination.next_page_token`. It retains the branch anchor turn and returns older events toward the session start.", "type": "string" } }, { "description": "Newest turn in the listing window (initial load only; ignored when `page_token` is set). Lists that turn and its ancestors, newest events first. Omit to use the session last turn.", "in": "query", "name": "last_turn_id", "required": false, "schema": { "description": "Newest turn in the listing window (initial load only; ignored when `page_token` is set). Lists that turn and its ancestors, newest events first. Omit to use the session last turn.", "type": "string" } }, { "description": "Page size. Defaults to and is capped at the server-configured maximum.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size. Defaults to and is capped at the server-configured maximum.", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionEventsResponse" } } }, "description": "Paginated session events." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid page token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller cannot read this session." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session not found." } }, "summary": "List session events", "tags": [ "Agent Sessions" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "list_events" } }, "/api/v1/sessions/{session_id}/grants": { "get": { "description": "List the subjects this session is shared with.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionGrantsResponse" } } }, "description": "Subjects the session is shared with." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "User does not have permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session not found." } }, "summary": "List session grants", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "list_grants" }, "post": { "description": "Share this session with subjects and remove access for others in one atomic request. Subjects get read access to the session, its turns and its events. A `tenant` subject, whose `subject_id` must be your tenant ID, shares with everyone in the tenant. Granting an existing subject or revoking one without access is a no-op. Returns every subject the session is shared with.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionGrantsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionGrantsResponse" } } }, "description": "Subjects the session is shared with after the change." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "User does not have permission." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session not found." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "A subject to grant is unknown or is the session creator, or a subject is both granted and revoked." } }, "summary": "Update session grants", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "update_grants" } }, "/api/v1/sessions/{session_id}/turns": { "get": { "description": "List turns for a session (newest first by default), token-paginated. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.", "parameters": [ { "description": "Service API key only: which user identity to assume. Currently only session-creator.", "in": "header", "name": "assume-user", "required": false, "schema": { "enum": [ "session-creator" ], "type": "string" } }, { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Page size. Defaults to 25, max 25.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "description": "Page size. Defaults to 25, max 25.", "maximum": 25, "minimum": 1, "type": "integer" } }, { "description": "Opaque token from a previous response `next_page_token`.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Opaque token from a previous response `next_page_token`.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTurnsResponse" } } }, "description": "Paginated turns." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid page token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller cannot read this session." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session not found." } }, "summary": "List turns in a session", "tags": [ "Agent Sessions" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "list_turns" }, "post": { "description": "Create a turn within a session and execute it.\nOnly the session creator may create turns.\nWhen `stream` is true (default), respond with a Server-Sent Events stream of turn events.\nWhen `stream` is false, return the turn immediately with `state.status: \"running\"` while execution continues in the background; use get turn or subscribe to observe completion.\nUse `previous_turn_id` to chain to the session's last turn (defaults to `auto`); use `none` for a new root.", "parameters": [ { "description": "Service API key only: which user identity to assume. Currently only session-creator.", "in": "header", "name": "assume-user", "required": false, "schema": { "enum": [ "session-creator" ], "type": "string" } }, { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTurnRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTurnResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/TurnStreamingEvent" } } }, "description": "When stream is false: the running turn. When stream is true: Server-Sent Events stream of turn events." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid Bearer token or auth cookie" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller is not the session creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session, prior turn, or referenced agent not found." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Requested action cannot be performed on the session because it is no longer usable." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Request body exceeds the configured maximum size (MAX_REQUEST_BODY_BYTES)." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The request is well-formed but cannot be processed: a referenced resource is missing (named agent, model, MCP server, skill, or sandbox provider), sandbox is required but unavailable (e.g. file uploads), or the turn input conflicts with current state (e.g. unresolved tool calls or approvals, tool name collision)." } }, "summary": "Create and execute a turn in a session", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "create_turn", "x-fern-streaming": { "format": "sse", "response": { "$ref": "#/components/schemas/GetTurnResponse" }, "response-stream": { "$ref": "#/components/schemas/TurnStreamingEvent" }, "resumable": false, "stream-condition": "$request.stream" } } }, "/api/v1/sessions/{session_id}/turns/{turn_id}": { "get": { "description": "Fetch a single turn by ID. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Turn identifier.", "in": "path", "name": "turn_id", "required": true, "schema": { "description": "Turn identifier.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTurnResponse" } } }, "description": "Turn data." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller cannot read this session." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session or turn not found." } }, "summary": "Get a turn", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "get_turn" } }, "/api/v1/sessions/{session_id}/turns/{turn_id}/download-sandbox-file": { "get": { "description": "Download a file from the sandbox this turn ran in. Paths come from the assistant's `sandbox_artifacts` block. Only the session creator may download.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Turn identifier.", "in": "path", "name": "turn_id", "required": true, "schema": { "description": "Turn identifier.", "minLength": 1, "type": "string" } }, { "description": "Absolute or sandbox-working-directory-relative file path, as listed in the assistant's `sandbox_artifacts` block.", "in": "query", "name": "path", "required": true, "schema": { "description": "Absolute or sandbox-working-directory-relative file path, as listed in the assistant's `sandbox_artifacts` block.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "File contents." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid path, or the path is a directory." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller is not the session creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session, turn, or file not found." }, "410": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox no longer exists." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Turn has no sandbox, or no sandbox provider is configured." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "File exceeds the maximum download size." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox infrastructure error." } }, "summary": "Download a file from the turn sandbox", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "download_sandbox_file" } }, "/api/v1/sessions/{session_id}/turns/{turn_id}/events": { "get": { "description": "Paginated persisted events for a turn (insertion order by default). Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Turn identifier.", "in": "path", "name": "turn_id", "required": true, "schema": { "description": "Turn identifier.", "minLength": 1, "type": "string" } }, { "description": "Page size. Defaults to and is capped at the server-configured maximum.", "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size. Defaults to and is capped at the server-configured maximum.", "minimum": 1, "type": "integer" } }, { "description": "Opaque token from a previous response `next_page_token`.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Opaque token from a previous response `next_page_token`.", "type": "string" } }, { "description": "Sort events by insertion order. Defaults to \"asc\".", "in": "query", "name": "order", "required": false, "schema": { "$ref": "#/components/schemas/ListTurnEventsOrder" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTurnEventsResponse" } } }, "description": "Paginated turn events." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid page token." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller cannot read this session." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session or turn not found." } }, "summary": "List turn events", "tags": [ "Agent Sessions" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "list_turn_events" }, "post": { "description": "Create events for a turn. Only the session creator may create them.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Turn identifier.", "in": "path", "name": "turn_id", "required": true, "schema": { "description": "Turn identifier.", "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTurnEventRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTurnEventResponse" } } }, "description": "Events created." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller is not the session creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Session, turn, or referenced agent not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Turn is terminal, running and not accepting events, or an event id already exists." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The referenced agent for this session no longer exists." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The executor ran the request and failed while applying the events." } }, "summary": "Create turn events", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "create_turn_events" } }, "/api/v1/sessions/{session_id}/turns/{turn_id}/subscribe": { "get": { "description": "Subscribe to the live SSE stream. Resume with from_event_id or after_event_id.", "parameters": [ { "description": "Session identifier.", "in": "path", "name": "session_id", "required": true, "schema": { "description": "Session identifier.", "maxLength": 64, "minLength": 1, "type": "string" } }, { "description": "Turn identifier.", "in": "path", "name": "turn_id", "required": true, "schema": { "description": "Turn identifier.", "minLength": 1, "type": "string" } }, { "description": "Deprecated. Rejected on new turns. Use from_event_id or after_event_id instead.", "in": "query", "name": "after_sequence_number", "required": false, "schema": { "description": "Deprecated. Rejected on new turns. Use from_event_id or after_event_id instead.", "minimum": 0, "type": [ "integer", "null" ] } }, { "description": "Inclusive cursor. Replay starts at the entry with this event id", "in": "query", "name": "from_event_id", "required": false, "schema": { "description": "Inclusive cursor. Replay starts at the entry with this event id", "minLength": 1, "type": "string" } }, { "description": "Exclusive cursor. Replay starts after the last entry with this event id.", "in": "query", "name": "after_event_id", "required": false, "schema": { "description": "Exclusive cursor. Replay starts after the last entry with this event id.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/TurnStreamingEvent" } } }, "description": "Server-Sent Events stream of turn events (deltas and lifecycle)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid query parameters." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Caller is not the session creator." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Turn not found." }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The turn stream is no longer available or resumable." } }, "summary": "Subscribe to a turn stream", "tags": [ "Agent Sessions" ], "x-fern-sdk-group-name": [ "sessions" ], "x-fern-sdk-method-name": "subscribe_to_turn", "x-fern-streaming": { "format": "sse", "resumable": false } } }, "/api/v1/settings/configuration": { "get": { "description": "Tenant-wide feature switches. Tenants with nothing saved yet get every switch enabled.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConfigurationResponse" } } }, "description": "The tenant configuration." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid Bearer token or auth cookie." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Authenticated but not an admin." } }, "summary": "Get the tenant configuration", "tags": [ "Configuration" ], "x-fern-sdk-group-name": [ "settings", "configuration" ], "x-fern-sdk-method-name": "get" }, "patch": { "description": "Updates the switches present in the body and leaves the rest. Turning web search off applies to new chats; chats already using it keep it.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConfigurationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConfigurationResponse" } } }, "description": "The saved tenant configuration." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid Bearer token or auth cookie." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Authenticated but not an admin." } }, "summary": "Update the tenant configuration", "tags": [ "Configuration" ], "x-fern-sdk-group-name": [ "settings", "configuration" ], "x-fern-sdk-method-name": "update" } }, "/api/v1/settings/mcp-servers": { "get": { "description": "Configured MCP servers with auth_status. Header secrets are redacted.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMCPServersResponse" } } }, "description": "All configured MCP servers" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the caller is authenticated but not an admin." } }, "summary": "List MCP servers", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "settings", "mcpServers" ], "x-fern-sdk-method-name": "list" }, "post": { "description": "Creates an MCP server by `name`. Fails if `name` is already taken. Runs DCR registration when `auth.type` is `dcr`. Header secrets: real value required; redacted with no stored value returns 400.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMCPServerRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMCPServerResponse" } } }, "description": "The created MCP server with auth_status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, or redacted header secret with no stored value to keep." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "An MCP server with this name already exists." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The server cannot satisfy `auth.type: dcr` (e.g. it advertises no registration_endpoint)." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported operation because the MCP servers are managed by external system" } }, "summary": "Create an MCP server", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "settings", "mcpServers" ], "x-fern-sdk-method-name": "create" }, "put": { "description": "Create or replace by `name`. Header secrets: real value sets/rotates; redacted keeps existing (400 if none).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMCPServerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMCPServerResponse" } } }, "description": "The saved MCP server with auth_status" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, or redacted header secret with no stored value to keep." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The server cannot satisfy `auth.type: dcr` (e.g. it advertises no registration_endpoint)." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported operation because the MCP servers are managed by external system" } }, "summary": "Create or replace an MCP server", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "settings", "mcpServers" ], "x-fern-sdk-method-name": "create_or_update" } }, "/api/v1/settings/mcp-servers/{name}": { "delete": { "description": "Deletes an MCP server by `name`, along with every stored OAuth token for it. Rejected while any agent still lists the server.", "parameters": [ { "description": "MCP server name.", "in": "path", "name": "name", "required": true, "schema": { "description": "MCP server name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMCPServerResponse" } } }, "description": "MCP server deleted." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "MCP server not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "One or more agents still use this MCP server." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported operation because the MCP servers are managed by external system" } }, "summary": "Delete an MCP server", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "settings", "mcpServers" ], "x-fern-sdk-method-name": "delete" }, "get": { "description": "A single MCP server by name, with nested live auth_status (settings / admin projection). Header auth values are redacted.", "parameters": [ { "description": "MCP server name.", "in": "path", "name": "name", "required": true, "schema": { "description": "MCP server name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMCPServerResponse" } } }, "description": "The MCP server" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "MCP server not found." } }, "summary": "Get a single MCP server by name", "tags": [ "MCP Servers" ], "x-fern-sdk-group-name": [ "settings", "mcpServers" ], "x-fern-sdk-method-name": "get" } }, "/api/v1/settings/memory-providers": { "get": { "description": "The configured provider for this tenant. `auth.api_key` is redacted when present.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMemoryProviderResponse" } } }, "description": "The configured memory provider." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid Bearer token or auth cookie." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Authenticated but not an admin." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "No memory provider configured." } }, "summary": "Get the memory provider", "tags": [ "Memory Providers" ], "x-fern-sdk-group-name": [ "settings", "memoryProviders" ], "x-fern-sdk-method-name": "get" }, "put": { "description": "Upserts the single memory provider for this tenant. `auth.api_key`: real value sets/rotates; redacted keeps existing (400 if none).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemoryProviderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMemoryProviderResponse" } } }, "description": "The saved provider." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, or redacted API key with no stored secret to keep." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported operation because memory providers are managed by an external system" } }, "summary": "Create or replace the memory provider", "tags": [ "Memory Providers" ], "x-fern-sdk-group-name": [ "settings", "memoryProviders" ], "x-fern-sdk-method-name": "create_or_update" } }, "/api/v1/settings/model-providers": { "get": { "description": "All configured providers with nested manifests.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelProvidersResponse" } } }, "description": "All configured model providers" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the caller is authenticated but not an admin." } }, "summary": "List configured model providers", "tags": [ "Models" ], "x-fern-sdk-group-name": [ "settings", "modelProviders" ], "x-fern-sdk-method-name": "list" }, "post": { "description": "Creates a provider (models included). Fails if `name` is already taken. Well-known types use `type` as `name` (one each); `custom` is named by the caller. `auth.api_key`: real value required; redacted with no stored secret returns 400.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModelProviderRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetModelProviderResponse" } } }, "description": "The created provider" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, or redacted API key with no stored secret to keep." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "A model provider with this name already exists." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported operation because the model providers are managed by external system" } }, "summary": "Create a model provider", "tags": [ "Models" ], "x-fern-sdk-group-name": [ "settings", "modelProviders" ], "x-fern-sdk-method-name": "create" }, "put": { "description": "Create or replace a provider (models included). Well-known types use `type` as `name` (one each); `custom` is named by the caller. `auth.api_key`: real value sets/rotates; redacted keeps existing (400 if none).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateModelProviderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetModelProviderResponse" } } }, "description": "The saved provider" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, or redacted API key with no stored secret to keep." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "The update drops a model that one or more agents still use." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported operation because the model providers are managed by external system" } }, "summary": "Create or replace a model provider", "tags": [ "Models" ], "x-fern-sdk-group-name": [ "settings", "modelProviders" ], "x-fern-sdk-method-name": "create_or_update" } }, "/api/v1/settings/model-providers/{name}": { "delete": { "description": "Deletes a provider and every model it declares. Rejected while any agent still uses one of them.", "parameters": [ { "description": "Model provider name.", "in": "path", "name": "name", "required": true, "schema": { "description": "Model provider name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteModelProviderResponse" } } }, "description": "Model provider deleted." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Model provider not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "One or more agents still use a model from this provider." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported operation because the model providers are managed by external system" } }, "summary": "Delete a model provider", "tags": [ "Models" ], "x-fern-sdk-group-name": [ "settings", "modelProviders" ], "x-fern-sdk-method-name": "delete" } }, "/api/v1/settings/sandbox-providers": { "get": { "description": "The single configured sandbox provider for this tenant. `auth.api_key` is redacted.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSandboxProviderResponse" } } }, "description": "The configured sandbox provider." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "No sandbox provider configured." } }, "summary": "Get the configured sandbox provider", "tags": [ "Sandboxes" ], "x-fern-sdk-group-name": [ "settings", "sandboxProviders" ], "x-fern-sdk-method-name": "get" }, "put": { "description": "Upserts the single sandbox provider for this tenant: creates it or replaces its entire configuration. `auth.api_key`: real value sets/rotates; redacted keeps existing (400 if none).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSandboxProviderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSandboxProviderResponse" } } }, "description": "The saved sandbox provider." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, or redacted API key with no stored secret to keep." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Sandbox provider rejected the provided API key." } }, "summary": "Create or replace the sandbox provider", "tags": [ "Sandboxes" ], "x-fern-sdk-group-name": [ "settings", "sandboxProviders" ], "x-fern-sdk-method-name": "create_or_update" } }, "/api/v1/settings/skills": { "get": { "description": "All configured skills with nested manifests (settings / admin projection).", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSkillsResponse" } } }, "description": "All configured skills." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the caller is authenticated but not an admin." } }, "summary": "List configured skills", "tags": [ "Skills" ], "x-fern-sdk-group-name": [ "settings", "skills" ], "x-fern-sdk-method-name": "list" }, "post": { "description": "Creates a skill keyed by `name`. Fails if `name` is already taken.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkillRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSkillResponse" } } }, "description": "The created skill." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "A skill with this name already exists." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported because skills are managed by an external system." } }, "summary": "Create a skill", "tags": [ "Skills" ], "x-fern-sdk-group-name": [ "settings", "skills" ], "x-fern-sdk-method-name": "create" }, "put": { "description": "Full upsert keyed by `name`: creates the skill or replaces its entire manifest.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkillRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSkillResponse" } } }, "description": "The saved skill." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported because skills are managed by an external system." } }, "summary": "Create or replace a skill", "tags": [ "Skills" ], "x-fern-sdk-group-name": [ "settings", "skills" ], "x-fern-sdk-method-name": "create_or_update" } }, "/api/v1/settings/skills/{name}": { "delete": { "description": "Deletes a skill by `name`. Rejected while any agent still lists the skill.", "parameters": [ { "description": "Skill name.", "in": "path", "name": "name", "required": true, "schema": { "description": "Skill name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSkillResponse" } } }, "description": "Skill deleted." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Skill not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "One or more agents still use this skill." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported because skills are managed by an external system." } }, "summary": "Delete a skill", "tags": [ "Skills" ], "x-fern-sdk-group-name": [ "settings", "skills" ], "x-fern-sdk-method-name": "delete" } }, "/api/v1/settings/web-search-providers": { "get": { "description": "The configured provider for this tenant. `auth.api_key` is redacted when present.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebSearchProviderResponse" } } }, "description": "The configured web search provider." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid Bearer token or auth cookie." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Authenticated but not an admin." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "No web search provider configured." } }, "summary": "Get the web search provider", "tags": [ "Web Search Providers" ], "x-fern-sdk-group-name": [ "settings", "webSearchProviders" ], "x-fern-sdk-method-name": "get" }, "put": { "description": "Upserts the single web search provider for this tenant. `auth.api_key`: real value sets/rotates; redacted keeps existing (400 if none).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebSearchProviderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebSearchProviderResponse" } } }, "description": "The saved provider." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid request body, or redacted API key with no stored secret to keep." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Unsupported operation because web-search providers are managed by an external system" } }, "summary": "Create or replace the web search provider", "tags": [ "Web Search Providers" ], "x-fern-sdk-group-name": [ "settings", "webSearchProviders" ], "x-fern-sdk-method-name": "create_or_update" } }, "/api/v1/skills": { "get": { "description": "Configured skills as a slim name/description list for the composer.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAvailableSkillsResponse" } } }, "description": "All configured skills (chat projection)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "OIDC is configured and the request has no valid session cookie." } }, "summary": "List skills for chat", "tags": [ "Skills" ], "x-fern-sdk-group-name": [ "skills" ], "x-fern-sdk-method-name": "list", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "List the skills you can add to an agent, each with its name and description. Use it to find a skill to reference in a manifest.", "name": "list_skills" } } }, "/api/v1/skills/versions": { "get": { "description": "Versions for one skill.", "parameters": [ { "description": "Skill name.", "in": "query", "name": "name", "required": true, "schema": { "description": "Skill name.", "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSkillVersionsResponse" } } }, "description": "Skill versions." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Authentication required." } }, "summary": "List skill versions", "tags": [ "Skills" ], "x-fern-sdk-group-name": [ "skills" ], "x-fern-sdk-method-name": "list_versions", "x-tfg-mcp": { "annotations": { "readOnlyHint": true }, "description": "List the available versions of a skill so you can pin a specific version when referencing it in an agent manifest.", "name": "list_skill_versions" } } }, "/api/v1/users": { "get": { "description": "List users in the tenant that sessions can be shared with. Searches email and display name, or looks up specific users with `ids`.", "parameters": [ { "description": "Case-insensitive substring match on email or display name.", "in": "query", "name": "query", "required": false, "schema": { "description": "Case-insensitive substring match on email or display name.", "maxLength": 200, "minLength": 1, "type": "string" } }, { "description": "Page size. Defaults to 25, max 100.", "in": "query", "name": "limit", "required": false, "schema": { "default": 25, "description": "Page size. Defaults to 25, max 100.", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque token from a previous response `next_page_token`.", "in": "query", "name": "page_token", "required": false, "schema": { "description": "Opaque token from a previous response `next_page_token`.", "type": "string" } }, { "description": "Return only these users (comma-separated ids, up to 100). Users that are unknown or inactive are omitted. Cannot be combined with `query` or `page_token`.", "in": "query", "name": "ids", "required": false, "schema": { "description": "Return only these users (comma-separated ids, up to 100). Users that are unknown or inactive are omitted. Cannot be combined with `query` or `page_token`.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUsersResponse" } } }, "description": "Paginated users." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestErrorResponse" } } }, "description": "Invalid query parameters or page token." } }, "summary": "List users", "tags": [ "Users" ], "x-fern-pagination": { "cursor": "$request.page_token", "next_cursor": "$response.pagination.next_page_token", "results": "$response.data" }, "x-fern-sdk-group-name": [ "users" ], "x-fern-sdk-method-name": "list" } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Internal" }, { "name": "Auth" }, { "name": "Users" }, { "name": "Capabilities" }, { "name": "Models" }, { "name": "MCP Servers" }, { "name": "Skills" }, { "name": "Sandboxes" }, { "name": "Web Search Providers" }, { "name": "Memory Providers" }, { "name": "Configuration" }, { "name": "Agents" }, { "name": "Schedules" }, { "name": "Agent Sessions" } ], "webhooks": {} }