{ "openapi": "3.1.0", "info": { "title": "Monet Controller API", "version": "0.1.0", "description": "Local Hono controller API for the Monet desktop application." }, "tags": [ { "name": "System", "description": "Health and controller metadata endpoints." }, { "name": "Sessions", "description": "Session lifecycle and history endpoints." }, { "name": "Providers", "description": "Provider, model catalog, and validation endpoints." }, { "name": "Runs", "description": "Run lifecycle endpoints such as interruption." }, { "name": "Connectors", "description": "External account connectors and connection status endpoints." } ], "components": { "schemas": { "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ], "example": "ok" }, "service": { "type": "string", "enum": [ "controller" ], "example": "controller" }, "version": { "type": "string", "example": "0.1.0" } }, "required": [ "status", "service", "version" ] }, "StopRunResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ], "example": true } }, "required": [ "ok" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string", "example": "Missing or invalid bearer token." } }, "required": [ "error", "message" ] }, "Session": { "type": "object", "properties": { "id": { "type": "string", "example": "ses_123" }, "title": { "type": "string", "example": "New chat" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-04-23T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-04-23T10:05:00.000Z" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "defaultProviderId": { "type": [ "string", "null" ], "example": null }, "defaultModelId": { "type": [ "string", "null" ], "example": null }, "messageCount": { "type": "integer", "minimum": 0, "example": 0 } }, "required": [ "id", "title", "createdAt", "updatedAt", "archivedAt", "defaultProviderId", "defaultModelId", "messageCount" ] }, "ListSessionsResponse": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } } }, "required": [ "sessions" ] }, "CreateSessionRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "providerId": { "type": "string", "minLength": 1 }, "modelId": { "type": "string", "minLength": 1 } } }, "SessionMessage": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_123" }, "sessionId": { "type": "string", "example": "ses_123" }, "runId": { "type": [ "string", "null" ], "example": "run_123" }, "role": { "type": "string", "example": "user" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-04-23T10:05:00.000Z" }, "uiMessage": { "example": { "id": "msg_123", "role": "user", "parts": [ { "type": "text", "text": "Hello" } ] } } }, "required": [ "id", "sessionId", "runId", "role", "createdAt" ] }, "SessionDetail": { "allOf": [ { "$ref": "#/components/schemas/Session" }, { "type": "object", "properties": { "workspacePath": { "type": [ "string", "null" ], "example": "/Users/example/Library/Application Support/Monet/session-workspaces/ses_abc123/workspace" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/SessionMessage" } } }, "required": [ "workspacePath", "messages" ] } ] }, "UpdateSessionRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "title" ] }, "ArchiveSessionResponse": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/Session" } }, "required": [ "session" ] }, "OpenWorkspaceDirectoryResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ], "example": true }, "workspacePath": { "type": "string", "example": "/Users/example/Library/Application Support/Monet/session-workspaces/ses_abc123/workspace" } }, "required": [ "ok", "workspacePath" ] }, "Provider": { "type": "object", "properties": { "id": { "type": "string", "example": "pro_123" }, "type": { "type": "string", "enum": [ "openai", "openrouter" ], "example": "openai" }, "displayName": { "type": "string", "example": "Provider" }, "baseUrl": { "type": [ "string", "null" ], "format": "uri", "example": null }, "defaultModelName": { "type": [ "string", "null" ], "example": null }, "enabled": { "type": "boolean", "example": true }, "timeoutMs": { "type": [ "integer", "null" ], "example": null }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" } }, "required": [ "id", "type", "displayName", "baseUrl", "defaultModelName", "enabled", "timeoutMs", "createdAt", "updatedAt" ] }, "ListProvidersResponse": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } } }, "required": [ "providers" ] }, "CreateProviderRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "openai", "openrouter" ], "example": "openai" }, "displayName": { "type": "string", "minLength": 1, "example": "My OpenAI Provider" }, "baseUrl": { "type": [ "string", "null" ], "format": "uri", "example": null }, "timeoutMs": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "example": null } }, "required": [ "type", "displayName" ] }, "UpdateProviderRequest": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "example": "My OpenAI Provider" }, "baseUrl": { "type": [ "string", "null" ], "format": "uri", "example": null }, "timeoutMs": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "example": null } } }, "ProviderModel": { "type": "object", "properties": { "id": { "type": "string", "example": "mod_123" }, "providerId": { "type": "string", "example": "pro_123" }, "modelName": { "type": "string", "example": "model-name" }, "displayName": { "type": "string", "example": "Model name" }, "supportsTools": { "type": "boolean", "example": false }, "supportsReasoning": { "type": "boolean", "example": false }, "enabled": { "type": "boolean", "example": true }, "capabilitiesJson": { "type": [ "string", "null" ], "example": null }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-04-23T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-04-23T10:00:00.000Z" } }, "required": [ "id", "providerId", "modelName", "displayName", "supportsTools", "supportsReasoning", "enabled", "capabilitiesJson", "createdAt", "updatedAt" ] }, "ListModelsResponse": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderModel" } } }, "required": [ "models" ] }, "CreateProviderModelRequest": { "type": "object", "properties": { "modelName": { "type": "string", "minLength": 1, "maxLength": 300, "example": "gpt-4.1-mini" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 300, "example": "GPT 4.1 Mini" }, "supportsTools": { "type": "boolean", "example": true }, "supportsReasoning": { "type": "boolean", "example": false } }, "required": [ "modelName" ] }, "CreateProviderModelWithProviderRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateProviderModelRequest" }, { "type": "object", "properties": { "providerId": { "type": "string", "minLength": 1, "example": "pro_123" } }, "required": [ "providerId" ] } ] }, "ValidateProviderResponse": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/Provider" }, "valid": { "type": "boolean", "example": true }, "reason": { "type": "string", "enum": [ "ok", "disabled", "no_enabled_models", "missing_default_model", "default_model_unresolved", "missing_credentials", "provider_api_error" ], "example": "ok" }, "message": { "type": "string", "example": "Provider configuration is valid." }, "defaultModelId": { "type": [ "string", "null" ], "example": null }, "defaultModelName": { "type": [ "string", "null" ], "example": null }, "availableModelCount": { "type": "integer", "minimum": 0, "example": 0 } }, "required": [ "provider", "valid", "reason", "message", "defaultModelId", "defaultModelName", "availableModelCount" ] }, "UpdateProviderModelRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true } }, "required": [ "enabled" ] }, "AuthorizedDirectory": { "type": "object", "properties": { "path": { "type": "string", "example": "/Users/example/Projects/monet" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-04-23T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-04-23T10:05:00.000Z" } }, "required": [ "path", "createdAt", "updatedAt" ] }, "ListAuthorizedDirectoriesResponse": { "type": "object", "properties": { "authorizedDirectories": { "type": "array", "items": { "$ref": "#/components/schemas/AuthorizedDirectory" } } }, "required": [ "authorizedDirectories" ] }, "ReplaceAuthorizedDirectoriesRequest": { "type": "object", "properties": { "paths": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 100 } }, "required": [ "paths" ] }, "ConnectorProviderComposioSettingsAuthConfigIds": { "type": "object", "properties": { "github": { "type": "string", "minLength": 1, "example": "github-auth-config-id" }, "notion": { "type": "string", "minLength": 1, "example": "notion-auth-config-id" }, "google_drive": { "type": "string", "minLength": 1, "example": "google-drive-auth-config-id" } } }, "ConnectorProviderComposioSettings": { "type": "object", "properties": { "key": { "type": "string", "example": "connector_provider_composio" }, "provider": { "type": "string", "enum": [ "composio" ], "example": "composio" }, "apiKeyConfigured": { "type": "boolean", "example": true }, "baseUrl": { "type": "string", "format": "uri", "example": "https://backend.composio.dev" }, "timeoutMs": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "example": null }, "authConfigIds": { "$ref": "#/components/schemas/ConnectorProviderComposioSettingsAuthConfigIds" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-04-23T10:05:00.000Z" } }, "required": [ "key", "provider", "apiKeyConfigured", "baseUrl", "timeoutMs", "authConfigIds", "updatedAt" ] }, "ConnectorProviderComposioSettingsRequest": { "type": "object", "properties": { "apiKey": { "type": [ "string", "null" ], "example": "abc123" }, "baseUrl": { "type": "string", "format": "uri", "example": "https://backend.composio.dev" }, "timeoutMs": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "example": 120000 }, "authConfigIds": { "$ref": "#/components/schemas/ConnectorProviderComposioSettingsAuthConfigIds" } } }, "Tool": { "type": "object", "properties": { "name": { "type": "string", "example": "read_file" }, "description": { "type": "string", "example": "Reads a UTF-8 text file from an authorized directory." }, "requiresConfirmation": { "type": "boolean", "example": true } }, "required": [ "name", "description", "requiresConfirmation" ] }, "ListToolsResponse": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } } }, "required": [ "tools" ] }, "ConnectorToolPolicy": { "type": "object", "properties": { "sideEffect": { "type": "string", "enum": [ "read", "write", "destructive", "external_send" ], "example": "read" }, "approval": { "type": "string", "enum": [ "never", "first_use", "always" ], "example": "never" } }, "required": [ "sideEffect", "approval" ] }, "ConnectorStatus": { "type": "string", "enum": [ "unavailable", "not_connected", "connected", "expired" ], "example": "not_connected" }, "ConnectorProviderErrorCode": { "type": "string", "enum": [ "connection_missing", "connection_expired", "rate_limited", "upstream_unavailable", "invalid_arguments", "forbidden", "tool_not_found", "provider_error" ], "example": "provider_error" }, "ConnectorCatalogCard": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "github", "notion", "google_drive" ], "example": "github" }, "displayName": { "type": "string", "example": "GitHub" }, "description": { "type": "string", "example": "Search repositories, issues, pull requests, commits, and releases." }, "category": { "type": "string", "enum": [ "developer", "productivity", "files" ], "example": "developer" }, "icon": { "type": "string", "example": "github" }, "featuredTools": { "type": "array", "items": { "type": "string" }, "example": [ "GITHUB_SEARCH_ISSUES_AND_PULL_REQUESTS" ] }, "enabledByDefault": { "type": "boolean", "example": true }, "minimumApprovalPolicy": { "$ref": "#/components/schemas/ConnectorToolPolicy" }, "capabilitySummaries": { "type": "array", "items": { "type": "string" }, "example": [ "Search and list repositories." ] }, "status": { "$ref": "#/components/schemas/ConnectorStatus" }, "connectedAccountLabel": { "type": "string", "example": "octocat" }, "lastErrorCode": { "$ref": "#/components/schemas/ConnectorProviderErrorCode" }, "lastErrorMessage": { "type": "string", "example": "Connector provider is not configured." } }, "required": [ "id", "displayName", "description", "category", "icon", "featuredTools", "enabledByDefault", "minimumApprovalPolicy", "capabilitySummaries", "status" ] }, "ListConnectorsResponse": { "type": "object", "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorCatalogCard" } } }, "required": [ "connectors" ] }, "ConnectorAccountMetadata": { "type": "object", "properties": { "accountLabel": { "type": "string", "example": "octocat" }, "accountId": { "type": "string", "example": "123456" }, "providerConnectionId": { "type": "string", "example": "conn_123" }, "providerConnectorId": { "type": "string", "example": "GITHUB" }, "connectedAt": { "type": "string", "format": "date-time", "example": "2026-04-27T10:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-04-27T10:05:00.000Z" } } }, "ConnectorServiceConnection": { "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/ConnectorStatus" }, { "example": "connected" } ] }, "connected": { "type": "boolean", "example": true }, "connectedAccountLabel": { "type": "string", "example": "octocat" }, "account": { "$ref": "#/components/schemas/ConnectorAccountMetadata" }, "lastErrorCode": { "allOf": [ { "$ref": "#/components/schemas/ConnectorProviderErrorCode" }, { "example": "connection_expired" } ] }, "lastErrorMessage": { "type": "string", "example": "Connector account credentials have expired." } }, "required": [ "status", "connected" ] }, "ConnectorAllowedTool": { "type": "object", "properties": { "providerToolId": { "type": "string", "example": "GITHUB_SEARCH_ISSUES_AND_PULL_REQUESTS" }, "displayName": { "type": "string", "example": "Search issues and pull requests" }, "summary": { "type": "string", "example": "Search issues and pull requests across accessible repositories." }, "policy": { "$ref": "#/components/schemas/ConnectorToolPolicy" } }, "required": [ "providerToolId", "displayName", "summary", "policy" ] }, "ConnectorDetail": { "allOf": [ { "$ref": "#/components/schemas/ConnectorCatalogCard" }, { "type": "object", "properties": { "providerConnectorId": { "type": "string", "example": "GITHUB" }, "connection": { "$ref": "#/components/schemas/ConnectorServiceConnection" }, "allowedTools": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorAllowedTool" } } }, "required": [ "providerConnectorId", "connection", "allowedTools" ] } ] }, "GetConnectorResponse": { "type": "object", "properties": { "connector": { "$ref": "#/components/schemas/ConnectorDetail" } }, "required": [ "connector" ] }, "StartConnectorConnectionResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "redirect_required", "connected", "pending" ], "example": "redirect_required" }, "connectorId": { "type": "string", "enum": [ "github", "notion", "google_drive" ], "example": "github" }, "providerConnectionId": { "type": "string", "example": "conn_123" }, "redirectUrl": { "type": "string", "format": "uri", "example": "https://accounts.provider.example/oauth/authorize?..." }, "expiresAt": { "type": "string", "format": "date-time", "example": "2026-04-27T10:05:00.000Z" } }, "required": [ "status", "connectorId" ] }, "StartConnectorConnectionRequest": { "type": "object", "properties": { "redirectUrl": { "type": "string", "format": "uri", "example": "monet://connectors/callback" } } }, "DisconnectConnectorConnectionResponse": { "type": "object", "properties": { "connectorId": { "type": "string", "enum": [ "github", "notion", "google_drive" ], "example": "github" }, "status": { "type": "string", "enum": [ "not_connected" ], "example": "not_connected" } }, "required": [ "connectorId", "status" ] }, "ListLiveArtifactsResponse": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "sessionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByRunId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByToolCallId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "contentType": { "type": "string", "enum": [ "html_page_v1" ], "default": "html_page_v1" }, "currentRevisionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128, "default": null }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "pinned": { "type": "boolean" }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 } }, "required": [ "id", "schemaVersion", "sessionId", "createdByRunId", "createdByToolCallId", "title", "slug", "description", "status", "pinned", "refreshStatus", "refreshStartedAt", "createdAt", "updatedAt", "lastRefreshedAt", "lastRefreshError" ] } } }, "required": [ "artifacts" ] }, "LiveArtifactJsonValue": { "type": [ "string", "number", "boolean", "object", "array", "null" ], "description": "A bounded JSON value for live artifact rendering and sanitized metadata.", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/LiveArtifactJsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LiveArtifactJsonValue" } } ] }, "LiveArtifactResponse": { "type": "object", "properties": { "artifact": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "sessionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByRunId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByToolCallId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "contentType": { "type": "string", "enum": [ "html_page_v1" ], "default": "html_page_v1" }, "currentRevisionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128, "default": null }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "pinned": { "type": "boolean" }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "artifactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "position": { "type": "integer", "minimum": 0 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "renderJson": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "markdown" ] }, "markdown": { "type": "string", "minLength": 0, "maxLength": 20000 } }, "required": [ "kind", "markdown" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "minLength": 1, "maxLength": 200 }, "caption": { "type": "string", "minLength": 0, "maxLength": 500 }, "trend": { "type": "string", "enum": [ "up", "down", "flat" ] } }, "required": [ "kind", "label", "value" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "list" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "subtitle": { "type": "string", "minLength": 0, "maxLength": 700 }, "url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" } }, "required": [ "title" ] }, "maxItems": 100 } }, "required": [ "kind", "items" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "table" ] }, "columns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 1, "maxItems": 30 }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 1000 }, "maxItems": 30 }, "maxItems": 200 } }, "required": [ "kind", "columns", "rows" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "link_card" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" }, "description": { "type": "string", "minLength": 0, "maxLength": 1000 }, "sourceLabel": { "type": "string", "minLength": 0, "maxLength": 120 } }, "required": [ "kind", "title", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "json" ] }, "value": { "$ref": "#/components/schemas/LiveArtifactJsonValue" } }, "required": [ "kind", "value" ] } ] }, "provenanceJson": { "type": [ "object", "null" ], "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "static", "tool", "connector_tool" ] }, "label": { "type": "string" }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string" }, "accountLabel": { "type": [ "string", "null" ] }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "querySummary": { "type": "string" }, "recordCount": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "refreshedAt": { "type": "string", "format": "date-time" } }, "required": [ "type" ] }, "maxItems": 20, "default": [] }, "notes": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "generatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "artifactId", "schemaVersion", "position", "title", "kind", "renderJson", "provenanceJson", "sourceJson", "refreshStatus", "refreshStartedAt", "lastRefreshedAt", "lastError", "createdAt", "updatedAt" ] } }, "document": { "type": [ "object", "null" ], "properties": { "format": { "type": "string", "enum": [ "html_template_v1" ] }, "sanitizedHtml": { "type": "string", "description": "HTML template markup. For dynamic or refreshable values, use canonical bindings like {{data.foo}}, data-bind=\"text:data.foo\", data-bind-attr=\"href:data.url\", data-bind-style=\"color:data.color\", or data-repeat=\"data.items\" instead of hardcoding connector/tool-derived values." }, "dataJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "dataSchemaJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "sanitizerVersion": { "type": "string", "minLength": 1, "maxLength": 80, "default": "basic-html-v1" } }, "default": null, "required": [ "format", "sanitizedHtml" ], "additionalProperties": false } }, "required": [ "id", "schemaVersion", "sessionId", "createdByRunId", "createdByToolCallId", "title", "slug", "description", "status", "pinned", "refreshStatus", "refreshStartedAt", "createdAt", "updatedAt", "lastRefreshedAt", "lastRefreshError", "tiles" ] } }, "required": [ "artifact" ] }, "UpdateLiveArtifactRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "pinned": { "type": "boolean" }, "archived": { "type": "boolean" }, "status": { "type": "string", "enum": [ "archived" ] } }, "additionalProperties": false }, "LiveArtifactRefreshResponse": { "type": "object", "properties": { "artifact": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "sessionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByRunId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByToolCallId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "contentType": { "type": "string", "enum": [ "html_page_v1" ], "default": "html_page_v1" }, "currentRevisionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128, "default": null }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "pinned": { "type": "boolean" }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "artifactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "position": { "type": "integer", "minimum": 0 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "renderJson": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "markdown" ] }, "markdown": { "type": "string", "minLength": 0, "maxLength": 20000 } }, "required": [ "kind", "markdown" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "minLength": 1, "maxLength": 200 }, "caption": { "type": "string", "minLength": 0, "maxLength": 500 }, "trend": { "type": "string", "enum": [ "up", "down", "flat" ] } }, "required": [ "kind", "label", "value" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "list" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "subtitle": { "type": "string", "minLength": 0, "maxLength": 700 }, "url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" } }, "required": [ "title" ] }, "maxItems": 100 } }, "required": [ "kind", "items" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "table" ] }, "columns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 1, "maxItems": 30 }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 1000 }, "maxItems": 30 }, "maxItems": 200 } }, "required": [ "kind", "columns", "rows" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "link_card" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" }, "description": { "type": "string", "minLength": 0, "maxLength": 1000 }, "sourceLabel": { "type": "string", "minLength": 0, "maxLength": 120 } }, "required": [ "kind", "title", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "json" ] }, "value": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "required": [ "kind", "value" ] } ] }, "provenanceJson": { "type": [ "object", "null" ], "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "static", "tool", "connector_tool" ] }, "label": { "type": "string" }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string" }, "accountLabel": { "type": [ "string", "null" ] }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "querySummary": { "type": "string" }, "recordCount": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "refreshedAt": { "type": "string", "format": "date-time" } }, "required": [ "type" ] }, "maxItems": 20, "default": [] }, "notes": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "generatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "artifactId", "schemaVersion", "position", "title", "kind", "renderJson", "provenanceJson", "sourceJson", "refreshStatus", "refreshStartedAt", "lastRefreshedAt", "lastError", "createdAt", "updatedAt" ] } }, "document": { "type": [ "object", "null" ], "properties": { "format": { "type": "string", "enum": [ "html_template_v1" ] }, "sanitizedHtml": { "type": "string", "description": "HTML template markup. For dynamic or refreshable values, use canonical bindings like {{data.foo}}, data-bind=\"text:data.foo\", data-bind-attr=\"href:data.url\", data-bind-style=\"color:data.color\", or data-repeat=\"data.items\" instead of hardcoding connector/tool-derived values." }, "dataJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "dataSchemaJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "sanitizerVersion": { "type": "string", "minLength": 1, "maxLength": 80, "default": "basic-html-v1" } }, "default": null, "required": [ "format", "sanitizedHtml" ], "additionalProperties": false } }, "required": [ "id", "schemaVersion", "sessionId", "createdByRunId", "createdByToolCallId", "title", "slug", "description", "status", "pinned", "refreshStatus", "refreshStartedAt", "createdAt", "updatedAt", "lastRefreshedAt", "lastRefreshError", "tiles" ] }, "failures": { "type": "array", "items": { "type": "object", "properties": { "tileId": { "type": "string", "example": "til_123" }, "tileTitle": { "type": "string", "example": "Recent invoices" }, "toolName": { "type": "string", "example": "stripe_list_invoices" }, "error": { "type": "string", "example": "Refresh tool is unavailable: stripe_list_invoices" } }, "required": [ "tileId", "tileTitle", "toolName", "error" ] } } }, "required": [ "artifact", "failures" ] }, "LiveArtifactRefreshDisabledResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "disabled": { "type": "boolean", "enum": [ true ], "example": true } }, "required": [ "disabled" ] } ] } }, "parameters": {} }, "paths": { "/api/health": { "get": { "tags": [ "System" ], "summary": "Report controller health", "description": "Returns a readiness payload for local controller orchestration.", "responses": { "200": { "description": "Controller is ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/runs/{runId}/stop": { "post": { "tags": [ "Runs" ], "summary": "Stop run", "description": "Requests interruption of an in-flight run and marks unfinished persisted state as interrupted.", "parameters": [ { "schema": { "type": "string", "example": "run_123" }, "required": true, "name": "runId", "in": "path" } ], "responses": { "200": { "description": "Run stop was accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopRunResponse" } } } }, "404": { "description": "The requested run was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The run could not be stopped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sessions": { "get": { "tags": [ "Sessions" ], "summary": "List sessions", "description": "Returns persisted sessions ordered by recent activity.", "responses": { "200": { "description": "Sessions fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSessionsResponse" } } } } } }, "post": { "tags": [ "Sessions" ], "summary": "Create session", "description": "Creates a blank session with optional provider and model defaults.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } } }, "responses": { "201": { "description": "Session created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Request body or provider/model selection is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The requested provider could not resolve a model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The session could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sessions/{sessionId}": { "get": { "tags": [ "Sessions" ], "summary": "Get session detail", "description": "Returns a single session and its persisted message history.", "parameters": [ { "schema": { "type": "string", "example": "ses_123" }, "required": true, "name": "sessionId", "in": "path" } ], "responses": { "200": { "description": "Session detail fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDetail" } } } }, "404": { "description": "The requested session was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The session detail could not be loaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Sessions" ], "summary": "Update session", "description": "Updates mutable session fields such as the title.", "parameters": [ { "schema": { "type": "string", "example": "ses_123" }, "required": true, "name": "sessionId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionRequest" } } } }, "responses": { "200": { "description": "Session updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Request body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested session was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The session could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Sessions" ], "summary": "Delete session", "description": "Deletes a session and recursively removes its session workspace.", "parameters": [ { "schema": { "type": "string", "example": "ses_123" }, "required": true, "name": "sessionId", "in": "path" } ], "responses": { "204": { "description": "Session deleted successfully." }, "404": { "description": "The requested session was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The session could not be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sessions/{sessionId}/archive": { "post": { "tags": [ "Sessions" ], "summary": "Archive session", "description": "Marks a session as archived without deleting its history.", "parameters": [ { "schema": { "type": "string", "example": "ses_123" }, "required": true, "name": "sessionId", "in": "path" } ], "responses": { "200": { "description": "Session archived successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveSessionResponse" } } } }, "404": { "description": "The requested session was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The session could not be archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/sessions/{sessionId}/workspace/open": { "post": { "tags": [ "Sessions" ], "summary": "Open session workspace directory", "description": "Validates the session, derives its workspace path server-side, and ensures the workspace directory exists before desktop opening.", "parameters": [ { "schema": { "type": "string", "example": "ses_123" }, "required": true, "name": "sessionId", "in": "path" } ], "responses": { "200": { "description": "Session workspace directory is ready to open.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenWorkspaceDirectoryResponse" } } } }, "404": { "description": "The requested session was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The session workspace directory could not be prepared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/providers": { "get": { "tags": [ "Providers" ], "summary": "List providers", "description": "Returns persisted providers ordered by enabled status and name.", "responses": { "200": { "description": "Providers fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListProvidersResponse" } } } } } }, "post": { "tags": [ "Providers" ], "summary": "Create provider", "description": "Creates a new provider record.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProviderRequest" } } } }, "responses": { "201": { "description": "Provider created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/providers/{providerId}": { "patch": { "tags": [ "Providers" ], "summary": "Update provider", "description": "Updates provider metadata such as API proxy URL and timeout.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "pro_123" }, "required": true, "name": "providerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderRequest" } } } }, "responses": { "200": { "description": "Provider updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Providers" ], "summary": "Delete provider", "description": "Deletes a provider record and its models.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "pro_123" }, "required": true, "name": "providerId", "in": "path" } ], "responses": { "204": { "description": "Provider deleted successfully." }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The provider cannot be deleted due to associated runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider could not be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/models": { "get": { "tags": [ "Providers" ], "summary": "List models", "description": "Returns all persisted provider models ordered by enabled status and provider.", "responses": { "200": { "description": "Models fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } } } } }, "/api/providers/{providerId}/models": { "get": { "tags": [ "Providers" ], "summary": "List models for provider", "description": "Returns persisted models for a single provider.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "pro_123" }, "required": true, "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "Provider models fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } }, "404": { "description": "The requested provider was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider models could not be loaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Providers" ], "summary": "Create provider model", "description": "Manually adds or enables a provider model without fetching the provider catalog.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "pro_123" }, "required": true, "name": "providerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProviderModelRequest" } } } }, "responses": { "201": { "description": "Provider model created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderModel" } } } }, "404": { "description": "The requested provider was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider model could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/provider-models": { "post": { "tags": [ "Providers" ], "summary": "Create provider model", "description": "Manually adds or enables a provider model without fetching the provider catalog.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProviderModelWithProviderRequest" } } } }, "responses": { "201": { "description": "Provider model created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderModel" } } } }, "404": { "description": "The requested provider was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider model could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/providers/{providerId}/catalog": { "post": { "tags": [ "Providers" ], "summary": "Fetch provider catalog", "description": "Fetches the external provider model catalog, persists it, and returns the updated persisted models.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "pro_123" }, "required": true, "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "Provider catalog fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListModelsResponse" } } } }, "404": { "description": "The requested provider was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider catalog could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/providers/{providerId}/validate": { "post": { "tags": [ "Providers" ], "summary": "Validate provider", "description": "Validates a persisted provider against current local configuration and enabled models.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "pro_123" }, "required": true, "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "Provider validation completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateProviderResponse" } } } }, "404": { "description": "The requested provider was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider validation could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/provider-models/{modelId}": { "patch": { "tags": [ "Providers" ], "summary": "Update provider model", "description": "Updates persisted provider-model selection state.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "mod_123" }, "required": true, "name": "modelId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProviderModelRequest" } } } }, "responses": { "200": { "description": "Provider model updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderModel" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The provider model could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/provider-credentials/{providerType}": { "get": { "tags": [ "Providers" ], "summary": "Get provider credential status", "description": "Returns whether a provider credential is available without exposing the credential value.", "parameters": [ { "schema": { "type": "string", "enum": [ "openai", "openrouter" ], "example": "openai" }, "required": true, "name": "providerType", "in": "path" } ], "responses": { "200": { "description": "Provider credential status fetched successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerType": { "type": "string", "enum": [ "openai", "openrouter" ] }, "hasCredential": { "type": "boolean" }, "source": { "type": "string", "enum": [ "env", "runtime", "none" ] }, "version": { "type": "integer", "minimum": 0 } }, "required": [ "providerType", "hasCredential", "source", "version" ] } } } } } }, "put": { "tags": [ "Providers" ], "summary": "Update runtime provider credential", "description": "Updates the running controller's in-memory credential for a provider without returning the credential value.", "parameters": [ { "schema": { "type": "string", "enum": [ "openai", "openrouter" ], "example": "openai" }, "required": true, "name": "providerType", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "apiKey" ] } } } }, "responses": { "200": { "description": "Provider credential updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerType": { "type": "string", "enum": [ "openai", "openrouter" ] }, "hasCredential": { "type": "boolean" }, "source": { "type": "string", "enum": [ "env", "runtime", "none" ] }, "version": { "type": "integer", "minimum": 0 } }, "required": [ "providerType", "hasCredential", "source", "version" ] } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Providers" ], "summary": "Clear runtime provider credential", "description": "Clears the running controller's in-memory credential for a provider. Environment credentials, if present, remain effective.", "parameters": [ { "schema": { "type": "string", "enum": [ "openai", "openrouter" ], "example": "openai" }, "required": true, "name": "providerType", "in": "path" } ], "responses": { "200": { "description": "Provider credential cleared successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "providerType": { "type": "string", "enum": [ "openai", "openrouter" ] }, "hasCredential": { "type": "boolean" }, "source": { "type": "string", "enum": [ "env", "runtime", "none" ] }, "version": { "type": "integer", "minimum": 0 } }, "required": [ "providerType", "hasCredential", "source", "version" ] } } } } } } }, "/api/settings/authorized-directories": { "get": { "tags": [ "Settings" ], "summary": "List authorized directories", "description": "Returns the persisted allowlist of authorized directories used by filesystem tools.", "responses": { "200": { "description": "Authorized directories fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuthorizedDirectoriesResponse" } } } } } }, "put": { "tags": [ "Settings" ], "summary": "Replace authorized directories", "description": "Replaces the persisted allowlist of authorized directories used by filesystem tools.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceAuthorizedDirectoriesRequest" } } } }, "responses": { "200": { "description": "Authorized directories updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuthorizedDirectoriesResponse" } } } }, "400": { "description": "The request body was invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/settings/connectors/composio": { "get": { "tags": [ "Settings" ], "summary": "Get Composio connector provider settings", "description": "Returns connector provider settings with sensitive values redacted.", "responses": { "200": { "description": "Connector provider settings fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorProviderComposioSettings" } } } } } }, "put": { "tags": [ "Settings" ], "summary": "Replace Composio connector provider settings", "description": "Replaces persisted Composio connector provider settings.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorProviderComposioSettingsRequest" } } } }, "responses": { "200": { "description": "Connector provider settings updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorProviderComposioSettings" } } } }, "400": { "description": "The request body was invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/tools": { "get": { "tags": [ "Tools" ], "summary": "List tools", "description": "Returns tools available from the in-process controller tool registry.", "responses": { "200": { "description": "Tools fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListToolsResponse" } } } } } } }, "/api/connectors": { "get": { "tags": [ "Connectors" ], "summary": "List connectors", "description": "Returns static connector catalog cards merged with connection status for this Monet install.", "responses": { "200": { "description": "Connectors fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConnectorsResponse" } } } } } } }, "/api/connectors/{connectorId}": { "get": { "tags": [ "Connectors" ], "summary": "Get connector detail", "description": "Returns connector detail, connection status, allowlisted tools, and approval policies for this Monet install.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "github" }, "required": true, "name": "connectorId", "in": "path" } ], "responses": { "200": { "description": "Connector fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConnectorResponse" } } } }, "400": { "description": "Invalid connector request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Connector credentials have expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Connector provider denied access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Connector not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Connector connection is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Connector provider rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Connector provider request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Connector provider is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/connectors/{connectorId}/connect": { "post": { "tags": [ "Connectors" ], "summary": "Start connector connection flow", "description": "Starts the provider OAuth flow using a cryptographically random single-use state bound to this Monet install.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "github" }, "required": true, "name": "connectorId", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartConnectorConnectionRequest" } } } }, "responses": { "200": { "description": "Connector connection flow started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartConnectorConnectionResponse" } } } }, "400": { "description": "Invalid connector request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Connector credentials have expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Connector provider denied access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Connector not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Connector connection is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Connector provider rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Connector provider request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Connector provider is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/connectors/{connectorId}/connection": { "delete": { "tags": [ "Connectors" ], "summary": "Disconnect connector", "description": "Revokes provider access when supported and marks the local connector connection disconnected for this Monet install.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "github" }, "required": true, "name": "connectorId", "in": "path" } ], "responses": { "200": { "description": "Connector disconnected successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectConnectorConnectionResponse" } } } }, "400": { "description": "Invalid connector request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Connector credentials have expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Connector provider denied access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Connector not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Connector connection conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Connector provider rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Connector provider request failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Connector provider is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/live-artifacts": { "get": { "tags": [ "Live Artifacts" ], "summary": "List live artifacts", "description": "Returns persisted live artifacts ordered with pinned artifacts first.", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ], "example": "false" }, "required": false, "name": "includeArchived", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "example": "ses_123" }, "required": false, "name": "sessionId", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d+$", "example": "50" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d+$", "example": "0" }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Live artifacts fetched successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListLiveArtifactsResponse" } } } }, "400": { "description": "Query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Live Artifacts" ], "summary": "Create live artifact", "description": "Creates a persisted HTML live artifact document with sandboxed markup and embedded JSON data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Short title for the HTML live artifact." }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000, "description": "Optional human-readable description." }, "sessionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "contentType": { "type": "string", "enum": [ "html_page_v1" ], "default": "html_page_v1", "description": "Must be html_page_v1." }, "document": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "html_template_v1" ] }, "sanitizedHtml": { "type": "string", "description": "HTML template markup. For dynamic or refreshable values, use canonical bindings like {{data.foo}}, data-bind=\"text:data.foo\", data-bind-attr=\"href:data.url\", data-bind-style=\"color:data.color\", or data-repeat=\"data.items\" instead of hardcoding connector/tool-derived values." }, "dataJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "dataSchemaJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "sanitizerVersion": { "type": "string", "minLength": 1, "maxLength": 80, "default": "basic-html-v1" } }, "required": [ "format", "sanitizedHtml" ], "additionalProperties": false, "description": "Required HTML page document. Put markup in sanitizedHtml and dynamic/refreshable values in dataJson. Bind data with canonical forms like {{data.foo}}, data-bind=\"text:data.foo\", data-bind-attr=\"href:data.url\", data-bind-style=\"color:data.color\", and data-repeat=\"data.items\". Do not send tiles or renderJson." } }, "required": [ "title", "document" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Live artifact created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveArtifactResponse" } } } }, "400": { "description": "Request body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The live artifact could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/live-artifacts/{artifactId}": { "get": { "tags": [ "Live Artifacts" ], "summary": "Get live artifact detail", "description": "Returns a single HTML live artifact document and refresh metadata.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "example": "art_123" }, "required": true, "name": "artifactId", "in": "path" } ], "responses": { "200": { "description": "Live artifact fetched successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactResponse" }, { "properties": { "artifact": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "sessionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByRunId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByToolCallId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "contentType": { "type": "string", "enum": [ "html_page_v1" ], "default": "html_page_v1" }, "currentRevisionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128, "default": null }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "pinned": { "type": "boolean" }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "artifactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "position": { "type": "integer", "minimum": 0 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "renderJson": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "markdown" ] }, "markdown": { "type": "string", "minLength": 0, "maxLength": 20000 } }, "required": [ "kind", "markdown" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "minLength": 1, "maxLength": 200 }, "caption": { "type": "string", "minLength": 0, "maxLength": 500 }, "trend": { "type": "string", "enum": [ "up", "down", "flat" ] } }, "required": [ "kind", "label", "value" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "list" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "subtitle": { "type": "string", "minLength": 0, "maxLength": 700 }, "url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" } }, "required": [ "title" ] }, "maxItems": 100 } }, "required": [ "kind", "items" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "table" ] }, "columns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 1, "maxItems": 30 }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 1000 }, "maxItems": 30 }, "maxItems": 200 } }, "required": [ "kind", "columns", "rows" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "link_card" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" }, "description": { "type": "string", "minLength": 0, "maxLength": 1000 }, "sourceLabel": { "type": "string", "minLength": 0, "maxLength": 120 } }, "required": [ "kind", "title", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "json" ] }, "value": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "required": [ "kind", "value" ] } ] }, "provenanceJson": { "type": [ "object", "null" ], "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "static", "tool", "connector_tool" ] }, "label": { "type": "string" }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string" }, "accountLabel": { "type": [ "string", "null" ] }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "querySummary": { "type": "string" }, "recordCount": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "refreshedAt": { "type": "string", "format": "date-time" } }, "required": [ "type" ] }, "maxItems": 20, "default": [] }, "notes": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "generatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "artifactId", "schemaVersion", "position", "title", "kind", "renderJson", "provenanceJson", "sourceJson", "refreshStatus", "refreshStartedAt", "lastRefreshedAt", "lastError", "createdAt", "updatedAt" ] } }, "document": { "type": [ "object", "null" ], "properties": { "format": { "type": "string", "enum": [ "html_template_v1" ] }, "sanitizedHtml": { "type": "string", "description": "HTML template markup. For dynamic or refreshable values, use canonical bindings like {{data.foo}}, data-bind=\"text:data.foo\", data-bind-attr=\"href:data.url\", data-bind-style=\"color:data.color\", or data-repeat=\"data.items\" instead of hardcoding connector/tool-derived values." }, "dataJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "dataSchemaJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "sanitizerVersion": { "type": "string", "minLength": 1, "maxLength": 80, "default": "basic-html-v1" } }, "default": null, "required": [ "format", "sanitizedHtml" ], "additionalProperties": false } }, "required": [ "id", "schemaVersion", "sessionId", "createdByRunId", "createdByToolCallId", "title", "slug", "description", "status", "pinned", "refreshStatus", "refreshStartedAt", "createdAt", "updatedAt", "lastRefreshedAt", "lastRefreshError", "tiles" ] } } } ] } } } }, "404": { "description": "The requested live artifact was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The live artifact could not be loaded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Live Artifacts" ], "summary": "Update live artifact", "description": "Updates title/description, pinned state, or archives the artifact.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "example": "art_123" }, "required": true, "name": "artifactId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLiveArtifactRequest" } } } }, "responses": { "200": { "description": "Live artifact updated successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactResponse" }, { "properties": { "artifact": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "sessionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByRunId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "createdByToolCallId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "slug": { "type": "string", "minLength": 1, "maxLength": 180, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "contentType": { "type": "string", "enum": [ "html_page_v1" ], "default": "html_page_v1" }, "currentRevisionId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128, "default": null }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ] }, "pinned": { "type": "boolean" }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "tiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "artifactId": { "type": "string", "minLength": 1, "maxLength": 128 }, "schemaVersion": { "type": "number", "enum": [ 1 ] }, "position": { "type": "integer", "minimum": 0 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "kind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "renderJson": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "markdown" ] }, "markdown": { "type": "string", "minLength": 0, "maxLength": 20000 } }, "required": [ "kind", "markdown" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "metric" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "value": { "type": "string", "minLength": 1, "maxLength": 200 }, "caption": { "type": "string", "minLength": 0, "maxLength": 500 }, "trend": { "type": "string", "enum": [ "up", "down", "flat" ] } }, "required": [ "kind", "label", "value" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "list" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "subtitle": { "type": "string", "minLength": 0, "maxLength": 700 }, "url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" } }, "required": [ "title" ] }, "maxItems": 100 } }, "required": [ "kind", "items" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "table" ] }, "columns": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 1, "maxItems": 30 }, "rows": { "type": "array", "items": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 1000 }, "maxItems": 30 }, "maxItems": 200 } }, "required": [ "kind", "columns", "rows" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "link_card" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "minLength": 1, "maxLength": 2000, "format": "uri" }, "description": { "type": "string", "minLength": 0, "maxLength": 1000 }, "sourceLabel": { "type": "string", "minLength": 0, "maxLength": 120 } }, "required": [ "kind", "title", "url" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "json" ] }, "value": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "required": [ "kind", "value" ] } ] }, "provenanceJson": { "type": [ "object", "null" ], "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "static", "tool", "connector_tool" ] }, "label": { "type": "string" }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string" }, "accountLabel": { "type": [ "string", "null" ] }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "querySummary": { "type": "string" }, "recordCount": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "refreshedAt": { "type": "string", "format": "date-time" } }, "required": [ "type" ] }, "maxItems": 20, "default": [] }, "notes": { "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "generatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "refreshStatus": { "type": "string", "enum": [ "idle", "refreshing", "failed" ] }, "refreshStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRefreshedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "artifactId", "schemaVersion", "position", "title", "kind", "renderJson", "provenanceJson", "sourceJson", "refreshStatus", "refreshStartedAt", "lastRefreshedAt", "lastError", "createdAt", "updatedAt" ] } }, "document": { "type": [ "object", "null" ], "properties": { "format": { "type": "string", "enum": [ "html_template_v1" ] }, "sanitizedHtml": { "type": "string", "description": "HTML template markup. For dynamic or refreshable values, use canonical bindings like {{data.foo}}, data-bind=\"text:data.foo\", data-bind-attr=\"href:data.url\", data-bind-style=\"color:data.color\", or data-repeat=\"data.items\" instead of hardcoding connector/tool-derived values." }, "dataJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "dataSchemaJson": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] }, "sourceJson": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "tool", "connector_tool" ] }, "toolName": { "type": "string", "minLength": 1, "maxLength": 200 }, "input": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/LiveArtifactJsonValue" }, { "type": [ "string", "number", "boolean", "object", "array", "null", "null" ] } ] } }, "connector": { "type": "object", "properties": { "connectorId": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectorName": { "type": "string", "minLength": 1, "maxLength": 120 }, "accountLabel": { "type": [ "string", "null" ], "minLength": 0, "maxLength": 200 }, "providerToolId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "required": [ "connectorId", "connectorName", "accountLabel", "providerToolId" ] }, "refreshPermission": { "type": "string", "enum": [ "manual_refresh_granted_for_read_only", "requires_confirmation" ] }, "outputMapping": { "type": "object", "properties": { "preferredKind": { "type": "string", "enum": [ "markdown", "metric", "list", "table", "link_card", "json" ] }, "dataPaths": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300, "pattern": "^(?:\\$|[A-Za-z0-9_$-]+)(?:\\.(?:[A-Za-z0-9_$-]+|\\d+))*$" }, "minItems": 1, "maxItems": 5 } ] }, "description": "Optional generic refresh mapping from dataJson destination paths to tool output source paths. Example: { stars: 'stargazers_count', owner: 'owner.login', repo: 'name' }. Source path arrays are fallbacks." } } } }, "required": [ "type" ] }, "sanitizerVersion": { "type": "string", "minLength": 1, "maxLength": 80, "default": "basic-html-v1" } }, "default": null, "required": [ "format", "sanitizedHtml" ], "additionalProperties": false } }, "required": [ "id", "schemaVersion", "sessionId", "createdByRunId", "createdByToolCallId", "title", "slug", "description", "status", "pinned", "refreshStatus", "refreshStartedAt", "createdAt", "updatedAt", "lastRefreshedAt", "lastRefreshError", "tiles" ] } } } ] } } } }, "400": { "description": "Request body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested live artifact was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The requested update conflicts with artifact state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The live artifact could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/live-artifacts/{artifactId}/refresh": { "post": { "tags": [ "Live Artifacts" ], "summary": "Refresh live artifact", "description": "Disabled by the Live Artifacts refresh phase gate until connector readiness gates pass. Static artifact creation, list, detail, update, pin, and archive remain available.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "example": "art_123" }, "required": true, "name": "artifactId", "in": "path" } ], "responses": { "200": { "description": "Live artifact refreshed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveArtifactRefreshResponse" } } } }, "400": { "description": "The live artifact could not be refreshed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "The requested live artifact was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A live artifact refresh is already in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "The live artifact refresh failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Live artifact refresh is not enabled in this increment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveArtifactRefreshDisabledResponse" } } } } } } } }, "webhooks": {} }