{ "openapi": "3.1.0", "info": { "title": "RunWhen Platform API", "version": "3.0.0", "description": "Programmatic access to RunWhen workspaces for observability, automation, and infrastructure operations. Covers workspaces; SLXs, SLIs, SLOs and runbooks; run sessions and run requests; issues; workflows and personas; code collections and codebundles; users; task search; and workspace activities." }, "servers": [ { "url": "https://papi.{domain}", "description": "RunWhen Platform API (PAPI). Path keys carry their own /api/vN prefix. SaaS: domain = beta.runwhen.com. Self-hosted: your global.domain (API at papi.).", "variables": { "domain": { "default": "beta.runwhen.com", "description": "Your RunWhen domain. SaaS beta: beta.runwhen.com. Self-hosted: your global.domain value." } } }, { "url": "https://agentfarm.{domain}", "description": "AgentFarm \u2014 AI orchestration for workspace chat. Same domain variable as PAPI (SaaS: beta.runwhen.com; self-hosted: global.domain).", "variables": { "domain": { "default": "beta.runwhen.com", "description": "Your RunWhen domain." } } } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "TokenRequest": { "type": "object", "required": [ "client_id", "client_secret", "grant_type" ], "properties": { "client_id": { "type": "string", "description": "OAuth client ID" }, "client_secret": { "type": "string", "description": "OAuth client secret" }, "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Grant type" } } }, "TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "JWT access token" }, "refresh_token": { "type": "string", "description": "Refresh token for obtaining new access token" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "description": "Seconds until access token expires" } } }, "RefreshTokenRequest": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string", "description": "Refresh token from initial auth" } } }, "Workspace": { "type": "object", "properties": { "name": { "type": "string", "description": "Workspace identifier" }, "displayName": { "type": "string", "description": "Human-readable workspace name" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WorkspaceList": { "type": "object", "properties": { "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } } }, "Issue": { "type": "object", "properties": { "id": { "type": "string", "description": "Issue ID" }, "title": { "type": "string", "description": "Issue title" }, "description": { "type": "string", "description": "Issue description" }, "severity": { "type": "integer", "minimum": 1, "maximum": 4, "description": "1=critical, 2=high, 3=medium, 4=low" }, "observedAt": { "type": "string", "format": "date-time" }, "slxName": { "type": "string", "description": "SLX that reported this issue" } } }, "IssueList": { "type": "object", "properties": { "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } } } }, "SLX": { "type": "object", "properties": { "name": { "type": "string", "description": "SLX short name (kebab-case)" }, "alias": { "type": "string", "description": "Human-readable display name" }, "statement": { "type": "string", "description": "SLX statement describing expected state" }, "intervalSeconds": { "type": "integer", "description": "How often the SLI runs" } } }, "SLXList": { "type": "object", "properties": { "slxs": { "type": "array", "items": { "$ref": "#/components/schemas/SLX" } } } }, "RunSessionCreateRequest": { "type": "object", "properties": { "slxName": { "type": "string", "description": "SLX to run" }, "location": { "type": "string", "description": "Runner location" }, "envVars": { "type": "object", "additionalProperties": { "type": "string" } } } }, "RunSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Run session ID" }, "slxName": { "type": "string" }, "status": { "type": "string", "enum": [ "RUNNING", "SUCCEEDED", "FAILED" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "RunSessionList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RunSession" } } } }, "RunRequest": { "type": "object", "properties": { "id": { "type": "string" }, "sessionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "SUCCEEDED", "FAILED" ] }, "taskName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "RunRequestList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RunRequest" } } } }, "SLI": { "type": "object", "properties": { "name": { "type": "string" }, "slxName": { "type": "string" }, "description": { "type": "string" }, "intervalSeconds": { "type": "integer" } } }, "SLO": { "type": "object", "properties": { "name": { "type": "string" }, "slxName": { "type": "string" }, "target": { "type": "number" }, "window": { "type": "string" } } }, "Runbook": { "type": "object", "properties": { "name": { "type": "string" }, "slxName": { "type": "string" }, "description": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "string" } } } }, "Workflow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "triggerType": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WorkflowList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } } } }, "WorkflowTriggerRequest": { "type": "object", "properties": { "payload": { "type": "object", "description": "Trigger-specific payload" } } }, "Persona": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "assistantConfig": { "type": "object" }, "createdAt": { "type": "string", "format": "date-time" } } }, "PersonaList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Persona" } } } }, "CodeCollection": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ref": { "type": "string", "description": "Branch or ref" }, "repositoryUrl": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CodeCollectionList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CodeCollection" } } } }, "Codebundle": { "type": "object", "properties": { "name": { "type": "string" }, "codeCollectionId": { "type": "string" }, "description": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "stats": { "type": "object" } } }, "CodebundleList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Codebundle" } } } }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "UserList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } }, "TaskSearchRequest": { "type": "object", "properties": { "query": { "type": "string", "description": "Natural language or keyword search" }, "limit": { "type": "integer", "default": 20 }, "filters": { "type": "object" } } }, "TaskSearchResult": { "type": "object", "properties": { "taskName": { "type": "string" }, "slxName": { "type": "string" }, "score": { "type": "number" }, "snippet": { "type": "string" } } }, "TaskSearchResultList": { "type": "object", "properties": { "count": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TaskSearchResult" } } } }, "Activity": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "userId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object" } } }, "ActivityList": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } } } }, "Rule": { "type": "object", "description": "A chat rule. Rules are loaded directly into the AI Assistant's prompt context to shape how findings are interpreted.", "properties": { "id": { "type": "integer", "description": "Unique rule identifier" }, "name": { "type": "string" }, "rule_content": { "type": "string", "description": "The instruction loaded into assistant context" }, "scope_type": { "type": "string", "enum": [ "workspace", "persona", "user" ] }, "scope_id": { "type": "string", "nullable": true, "description": "Scope target (workspace name, persona full name, or user email)" }, "workspace_name": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "RuleCreate": { "type": "object", "required": [ "name", "rule_content", "scope_type" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "rule_content": { "type": "string", "description": "Instruction text loaded into assistant context" }, "scope_type": { "type": "string", "enum": [ "workspace", "persona", "user" ], "description": "workspace/persona require workspace admin; user scope is self-owned" }, "scope_id": { "type": "string", "nullable": true, "description": "Required for persona scope (persona short name). Ignored for workspace scope and forced to the caller for user scope." }, "is_active": { "type": "boolean", "default": true } } }, "RuleUpdate": { "type": "object", "description": "Partial update \u2014 omitted fields are left unchanged.", "properties": { "name": { "type": "string" }, "rule_content": { "type": "string" }, "scope_type": { "type": "string", "enum": [ "workspace", "persona", "user" ] }, "scope_id": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "Command": { "type": "object", "description": "A chat command (slash-command). Commands package a repeatable investigation procedure that an assistant runs on demand or on a schedule.", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "command_content": { "type": "string", "description": "The prompt the assistant runs" }, "description": { "type": "string", "nullable": true }, "scope_type": { "type": "string", "enum": [ "workspace", "persona", "user" ] }, "scope_id": { "type": "string", "nullable": true }, "workspace_name": { "type": "string" }, "is_active": { "type": "boolean" }, "cron_schedule": { "type": "string", "nullable": true, "description": "Cron expression for scheduled runs (optional)" }, "sink_configs": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Delivery sinks for scheduled command artifacts (e.g. Slack)" }, "assistant_name": { "type": "string", "nullable": true, "description": "Assistant persona that runs scheduled fires" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "CommandCreate": { "type": "object", "required": [ "name", "command_content", "scope_type" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "command_content": { "type": "string", "minLength": 1, "description": "The prompt the assistant runs" }, "scope_type": { "type": "string", "enum": [ "workspace", "persona", "user" ] }, "scope_id": { "type": "string", "nullable": true, "description": "Required for persona scope (persona short name)" }, "description": { "type": "string" }, "is_active": { "type": "boolean", "default": true }, "cron_schedule": { "type": "string", "description": "Cron expression to schedule the command (optional)" }, "sink_configs": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Delivery sinks for scheduled artifacts (optional)" }, "assistant_name": { "type": "string", "description": "Assistant persona for scheduled fires (optional)" }, "run_as_user": { "type": "string", "description": "User identity scheduled fires run as (optional)" }, "max_runs": { "type": "integer", "description": "Cap on total scheduled runs (optional)" }, "auto_approve_readonly": { "type": "boolean", "description": "Auto-approve read-only tasks on scheduled fires (optional)" } } }, "CommandUpdate": { "type": "object", "description": "Partial update \u2014 omitted fields are left unchanged. An empty command_content is rejected.", "properties": { "name": { "type": "string" }, "command_content": { "type": "string", "minLength": 1 }, "scope_type": { "type": "string", "enum": [ "workspace", "persona", "user" ] }, "scope_id": { "type": "string", "nullable": true }, "description": { "type": "string" }, "is_active": { "type": "boolean" }, "cron_schedule": { "type": "string" }, "sink_configs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "assistant_name": { "type": "string" }, "max_runs": { "type": "integer" }, "schedule_paused": { "type": "boolean" }, "auto_approve_readonly": { "type": "boolean" } } }, "PaginatedList": { "type": "object", "description": "Standard paginated envelope used by chat-config list endpoints.", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "AssistantPayload": { "type": "object", "description": "Full assistant (persona) configuration for the v4 upsert. The sync is a FULL upsert \u2014 any omitted field resets to its default.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Full persona name: {workspace}--{shortName}" }, "fullName": { "type": "string", "description": "Human-readable display name" }, "description": { "type": "string", "description": "What the assistant specializes in" }, "avatarUrl": { "type": "string", "nullable": true, "description": "Avatar image URL (e.g. /personas/Man1-Happy.svg)" }, "filterConfidenceThreshold": { "type": "number", "default": 0.5, "description": "Confidence threshold for filtering results (0-1)" }, "filterIssueSelectionStrategy": { "type": "string", "default": "MOST_SEVERE" }, "filterCodebundleTaskTags": { "type": "array", "items": { "type": "string" }, "description": "Only surface tasks tagged with these" }, "filterStopWords": { "type": "array", "items": { "type": "string" } }, "filterScope": { "type": "string", "nullable": true }, "searchFilters": { "type": "object", "additionalProperties": true, "description": "Vector-search filter operators" }, "runConfidenceThreshold": { "type": "number", "default": 0.95, "description": "Confidence threshold for automatic task runs (0-1)" }, "runConfig": { "type": "object", "additionalProperties": true, "description": "Run allow/disallow/budget settings" } } }, "AssistantSyncRequest": { "type": "object", "required": [ "payload" ], "properties": { "payload": { "$ref": "#/components/schemas/AssistantPayload" } } }, "Assistant": { "type": "object", "description": "An AI Assistant (persona). Its short name is the persona_name used by workspace chat.", "properties": { "name": { "type": "string" }, "shortName": { "type": "string" }, "fullName": { "type": "string" }, "description": { "type": "string" }, "avatarUrl": { "type": "string", "nullable": true }, "filterConfidenceThreshold": { "type": "number" }, "filterIssueSelectionStrategy": { "type": "string" }, "filterCodebundleTaskTags": { "type": "array", "items": { "type": "string" } }, "filterStopWords": { "type": "array", "items": { "type": "string" } }, "searchFilters": { "type": "object", "additionalProperties": true }, "runConfidenceThreshold": { "type": "number" }, "runConfig": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "AuthorRunCreate": { "type": "object", "description": "Execute a script on a runner for testing (Tool Builder). Provides the raw script source, location, and config.", "required": [ "command", "location", "run_type", "interpreter" ], "properties": { "command": { "type": "string", "description": "Full script source code" }, "location": { "type": "string", "description": "Runner location (from GET .../runners)" }, "run_type": { "type": "string", "enum": [ "task", "sli" ] }, "interpreter": { "type": "string", "enum": [ "bash", "python" ] }, "envVars": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Environment variables" }, "secretVars": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map env var name \u2192 workspace secret key" } } }, "AuthorRunResponse": { "type": "object", "properties": { "run_id": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": true }, "SyncRequest": { "type": "object", "description": "Upsert envelope for SLX/Runbook/SLI sync. The payload shape matches the target resource.", "required": [ "payload" ], "properties": { "payload": { "type": "object", "additionalProperties": true } } }, "SlxSyncPayload": { "type": "object", "description": "SLX upsert payload (for POST /slxs/sync, wrapped in SyncRequest.payload).", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Full SLX name: {workspace}--{shortName}" }, "alias": { "type": "string", "description": "Human-readable display name" }, "statement": { "type": "string", "description": "What should be true (e.g. 'All pods should be running')" }, "owners": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Must include access + data tags" }, "imageUrl": { "type": "string" }, "additionalContext": { "type": "object", "additionalProperties": true } } }, "ResourceSelectorV4": { "type": "object", "description": "Tag match rule for note resourceSelectors. Multiple selectors in the list are ORed; keys within matchTags are ANDed.", "properties": { "matchTags": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Tag key/value equalities, ANDed together" } } }, "NoteResourceLinkV4": { "type": "object", "description": "A materialized note\u2192resource attachment resolved by the platform reconciler.", "properties": { "resourcePath": { "type": "string", "description": "Concrete resource path the note attaches to" }, "matchReason": { "type": "string", "description": "\"explicitPath\" | \"selector\"" }, "matchedSelector": { "type": "integer", "nullable": true, "description": "Index into resourceSelectors (null for explicit paths)" } } }, "NoteCreateV4": { "type": "object", "required": [ "content" ], "properties": { "title": { "type": "string", "nullable": true, "maxLength": 255, "description": "Short note title" }, "content": { "type": "string", "minLength": 1, "maxLength": 20000, "description": "Note content" }, "resourcePaths": { "type": "array", "items": { "type": "string" }, "description": "Canonical resource paths to scope the note. Omit or leave empty for a global note." }, "resourceSelectors": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceSelectorV4" }, "description": "Tag selectors resolved to resources by the platform" }, "abstractEntities": { "type": "array", "items": { "type": "string" }, "description": "Normalized entity tokens (optional)" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Author-facing labels" }, "status": { "type": "string", "enum": [ "active", "deprecated" ], "default": "active" } } }, "NoteUpdateV4": { "type": "object", "description": "Partial update \u2014 omitted fields are left unchanged.", "properties": { "title": { "type": "string", "nullable": true, "maxLength": 255 }, "content": { "type": "string", "minLength": 1, "maxLength": 20000 }, "resourcePaths": { "type": "array", "items": { "type": "string" } }, "resourceSelectors": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceSelectorV4" } }, "abstractEntities": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "deprecated" ] }, "verified": { "type": "boolean" } } }, "NoteResponseV4": { "type": "object", "description": "Full note response. Notes feed the Knowledge Overlay Graph that AI Assistants consult during investigations.", "properties": { "noteId": { "type": "string", "format": "uuid", "description": "Unique note identifier" }, "title": { "type": "string", "nullable": true, "description": "Short note title" }, "content": { "type": "string", "description": "Note content (max 20000 chars)" }, "resourcePaths": { "type": "array", "items": { "type": "string" }, "description": "Authored explicit resource paths" }, "resourceSelectors": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceSelectorV4" }, "description": "Authored tag selectors" }, "resourceLinks": { "type": "array", "items": { "$ref": "#/components/schemas/NoteResourceLinkV4" }, "description": "Resolved concrete attachments (reconciler-owned)" }, "lastResolvedAt": { "type": "string", "format": "date-time", "nullable": true }, "resolutionState": { "type": "string", "nullable": true, "description": "ok | pending | error" }, "indexingState": { "type": "string", "nullable": true, "description": "USearch index state (completed | failed | queued | ...)" }, "abstractEntities": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Author-facing labels" }, "status": { "type": "string", "description": "Note lifecycle status (active | deprecated)" }, "verified": { "type": "boolean", "description": "Whether note is human-verified" }, "authorEmail": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "sourceKind": { "type": "string", "description": "Origin: \"manual\" or external (e.g. \"git\")" }, "source": { "type": "string", "nullable": true, "description": "Origin/collection (e.g. repo URL)" }, "sourceId": { "type": "string", "nullable": true, "description": "Identifier within the source (e.g. file path)" }, "sourceRef": { "type": "string", "nullable": true, "description": "Version pointer at last sync (e.g. commit)" }, "readOnly": { "type": "boolean", "description": "True for externally-synced notes (edit at source)" } } }, "NoteSummaryV4": { "type": "object", "description": "Lightweight note representation for LIST responses (view=summary). Omits content and resourceLinks.", "properties": { "noteId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "resourcePaths": { "type": "array", "items": { "type": "string" } }, "resourceSelectors": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceSelectorV4" } }, "abstractEntities": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "resolutionState": { "type": "string", "nullable": true }, "indexingState": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "sourceKind": { "type": "string" }, "source": { "type": "string", "nullable": true }, "sourceId": { "type": "string", "nullable": true }, "sourceRef": { "type": "string", "nullable": true }, "readOnly": { "type": "boolean" } } }, "NoteDiagnosticV4": { "type": "object", "description": "Validation diagnostic from a note sync/import operation.", "properties": { "level": { "type": "string", "description": "\"error\" | \"warning\"" }, "code": { "type": "string" }, "field": { "type": "string", "nullable": true }, "message": { "type": "string" } } }, "NoteSyncRequestV4": { "type": "object", "description": "Publish (upsert) a KB note from an external source. Content is the full markdown note with YAML frontmatter.", "required": [ "source", "sourceId", "content" ], "properties": { "sourceKind": { "type": "string", "default": "git", "description": "Origin type, e.g. \"git\"" }, "source": { "type": "string", "description": "Origin/collection (e.g. repo URL)" }, "sourceId": { "type": "string", "description": "Stable id within the source (e.g. file path)" }, "sourceRef": { "type": "string", "nullable": true, "description": "Version pointer (e.g. commit)" }, "sourceMetadata": { "type": "object", "nullable": true, "additionalProperties": true }, "content": { "type": "string", "description": "Markdown note with YAML frontmatter" }, "dryRun": { "type": "boolean", "default": false, "description": "Validate only; write nothing" } } }, "NoteSyncResponseV4": { "type": "object", "description": "Result of a note sync (upsert) operation.", "properties": { "status": { "type": "string", "description": "created | updated | unchanged | rejected" }, "applied": { "type": "boolean" }, "ok": { "type": "boolean" }, "noteId": { "type": "string", "nullable": true }, "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/NoteDiagnosticV4" } } } }, "NoteDeleteRequestV4": { "type": "object", "description": "Batch-delete notes from one source by sourceId.", "required": [ "source", "sourceIds" ], "properties": { "sourceKind": { "type": "string", "default": "git" }, "source": { "type": "string" }, "sourceIds": { "type": "array", "items": { "type": "string" } }, "dryRun": { "type": "boolean", "default": false } } }, "NoteDeleteResultV4": { "type": "object", "properties": { "sourceId": { "type": "string" }, "status": { "type": "string", "description": "deleted | not_found" } } }, "NoteDeleteResponseV4": { "type": "object", "properties": { "applied": { "type": "boolean" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NoteDeleteResultV4" } } } }, "ResourcePathsResponseV4": { "type": "object", "properties": { "resourcePaths": { "type": "array", "items": { "type": "string" } } } }, "TagKeyValuesV4": { "type": "object", "properties": { "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "valueCount": { "type": "integer" } } }, "WorkspaceTagsResponseV4": { "type": "object", "properties": { "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagKeyValuesV4" } } } }, "ServiceAccountTokenScope": { "type": "object", "properties": { "id": { "type": "integer" }, "workspaceId": { "type": "integer" }, "workspaceName": { "type": "string" }, "role": { "type": "string" } } }, "ServiceAccountTokenCreate": { "type": "object", "required": [ "name" ], "description": "Create a token scoped to the workspace in the URL path.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable label for the token" }, "role": { "type": "string", "enum": [ "admin", "readwrite", "readandrun", "readandrunwithassistant", "readonly" ], "default": "readonly", "description": "Workspace permission role granted to the token" }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 3650, "nullable": true, "description": "Token lifetime in days. Omit for the platform default (~10 years)." } } }, "ServiceAccountTokenScopeUpdate": { "type": "object", "required": [ "workspaceId", "role" ], "properties": { "workspaceId": { "type": "integer" }, "role": { "type": "string", "enum": [ "admin", "readwrite", "readandrun", "readandrunwithassistant", "readonly" ] } } }, "ServiceAccountToken": { "type": "object", "description": "Metadata for an admin-managed service account token (JWT secret is never returned again after create).", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tokenSuffix": { "type": "string", "description": "Last 8 characters of the JWT for identification" }, "createdByName": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "isRevoked": { "type": "boolean" }, "isExpired": { "type": "boolean" }, "isActive": { "type": "boolean" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceAccountTokenScope" } } } }, "ServiceAccountTokenCreateResponse": { "allOf": [ { "$ref": "#/components/schemas/ServiceAccountToken" }, { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "Full JWT access token \u2014 shown once at creation; store securely." } } } ] }, "ServiceAccountTokenList": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceAccountToken" } }, "total": { "type": "integer" } } }, "WorkspaceChatRequest": { "type": "object", "required": [ "userId", "message", "sessionId" ], "description": "Start or continue a workspace chat turn. Set sessionId to null to create a new session; reuse the sessionId from the first SSE frame on follow-up turns. userId must be a valid email.", "properties": { "userId": { "type": "string", "format": "email", "description": "Caller identity \u2014 sessions are keyed on this value" }, "message": { "type": "string", "description": "User message for this turn" }, "sessionId": { "type": "string", "nullable": true, "description": "Existing session id, or null to start a new session" }, "personaName": { "type": "string", "nullable": true, "description": "Assistant (persona) short name. Omit for the workspace default." }, "workspaceName": { "type": "string", "description": "Optional when workspace is in the URL path" }, "source": { "type": "string", "enum": [ "ui", "slack", "teams" ], "default": "ui", "description": "Chat surface \u2014 affects prompt-hub override resolution" }, "enableScrubbing": { "type": "boolean", "default": true }, "kbSearchEnabled": { "type": "boolean", "default": false }, "autoApproveReadonly": { "type": "boolean", "default": false, "description": "When true and sessionId is null, seed auto-approve for read-only task runs on the new session" }, "contextMessages": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } } }, "description": "Prior messages to seed session context (e.g. Slack thread history)" } }, "additionalProperties": false }, "AbortChatRequest": { "type": "object", "required": [ "userId" ], "properties": { "userId": { "type": "string", "format": "email", "description": "Must match the userId that owns the session" } } }, "AbortChatResponse": { "type": "object", "properties": { "abortRequested": { "type": "boolean" }, "subscribers": { "type": "integer", "description": "Workers that received the abort signal" } } }, "ChatExportUrlRequest": { "type": "object", "required": [ "userId", "sessionId" ], "properties": { "userId": { "type": "string", "format": "email" }, "sessionId": { "type": "string" }, "ttlSeconds": { "type": "integer", "nullable": true, "description": "Optional link lifetime" } } }, "ChatExportUrlResponse": { "type": "object", "properties": { "exportUrl": { "type": "string", "description": "Relative path to open the read-only chat export in the RunWhen UI" } } }, "ChatSseEvent": { "type": "object", "description": "One SSE `data:` JSON payload from a chat-pro stream.", "properties": { "sessionId": { "type": "string", "nullable": true }, "invocationId": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true, "description": "Assistant text (partial or final)" }, "toolMessage": { "type": "string", "nullable": true }, "partial": { "type": "boolean", "nullable": true, "description": "True while streaming incremental text" }, "personaName": { "type": "string", "nullable": true }, "widgets": { "type": "array", "items": { "type": "object" } }, "functionCalls": { "type": "array", "items": { "type": "object" } }, "functionResponses": { "type": "array", "items": { "type": "object" } }, "resourceScope": { "type": "object", "nullable": true }, "aborted": { "type": "boolean" }, "errorMessage": { "type": "string", "nullable": true } }, "additionalProperties": true }, "RunnerWorker": { "type": "object", "description": "One worker process within a runner's codebundle worker pool.", "properties": { "workerId": { "type": "string" }, "workerPoolId": { "type": "string" }, "pollState": { "type": "string", "description": "Current poll state, e.g. `executing` or `idle`." }, "overallHealth": { "type": "string", "description": "`healthy` | `degraded` | `unhealthy`." }, "reportedAt": { "type": "string", "format": "date-time" }, "uptimeSeconds": { "type": "integer" }, "tasksProcessed": { "type": "integer" }, "tasksSucceeded": { "type": "integer" }, "tasksFailed": { "type": "integer" }, "lastTaskSuccess": { "type": "boolean" }, "lastTaskDurationMs": { "type": "integer" }, "pidUsagePct": { "type": "number" }, "pidUsageLimit": { "type": "integer" } } }, "RunnerWorkerPool": { "type": "object", "description": "Aggregated health and throughput for one codebundle worker pool on a runner.", "properties": { "workerCount": { "type": "integer" }, "overallHealth": { "type": "string", "description": "`healthy` | `degraded` | `unhealthy`." }, "tasksProcessed": { "type": "integer" }, "tasksSucceeded": { "type": "integer" }, "tasksFailed": { "type": "integer" }, "lastReportedAt": { "type": "string", "format": "date-time" }, "workers": { "type": "array", "items": { "$ref": "#/components/schemas/RunnerWorker" } } } }, "AuthorizedRunner": { "type": "object", "description": "A runner location authorized for the workspace, with heartbeat-derived health and per-pool worker status.", "properties": { "name": { "type": "string", "description": "Runner/location display name." }, "value": { "type": "string", "description": "Location identifier (`{workspace}--{location}`)." }, "health": { "type": "string", "enum": [ "online", "stale", "unknown" ], "description": "Derived from heartbeat freshness." }, "lastHeartbeat": { "type": "string", "format": "date-time", "nullable": true }, "secondsSinceHeartbeat": { "type": "number", "nullable": true }, "workerPools": { "type": "object", "nullable": true, "description": "Codebundle worker pools on this runner, keyed by pool id; each value reports the pool's live worker health and throughput.", "additionalProperties": { "$ref": "#/components/schemas/RunnerWorkerPool" } } } } } }, "paths": { "/api/v3/token/": { "post": { "summary": "Get auth token", "description": "Obtain an access token using client credentials. No bearer auth required.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "Token issued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "example": { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "rt_abc123xyz", "token_type": "Bearer", "expires_in": 3600 } } } } } } }, "/api/v3/token/refresh/": { "post": { "summary": "Refresh token", "description": "Obtain a new access token using a refresh token. No bearer auth required.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } } }, "responses": { "200": { "description": "New token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } } } } }, "/api/v3/workspaces/": { "get": { "summary": "List workspaces", "description": "List all workspaces the authenticated user or client can access.", "responses": { "200": { "description": "List of workspaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceList" }, "example": { "workspaces": [ { "name": "my-infra", "displayName": "My Infrastructure", "createdAt": "2024-01-15T10:00:00Z" } ] } } } } } } }, "/api/v3/workspaces/{workspace}/issues/": { "get": { "summary": "List issues", "description": "List issues for a workspace, optionally filtered by severity.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "severity", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 4 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueList" }, "example": { "issues": [ { "id": "iss_abc123", "title": "Pod not ready", "description": "Pod nginx-xyz in namespace default is not ready", "severity": 2, "observedAt": "2024-03-10T14:30:00Z", "slxName": "k8s-pod-health" } ] } } } } } } }, "/api/v3/workspaces/{workspace}/issues/{issueId}/": { "get": { "summary": "Get issue detail", "description": "Retrieve detailed information about a specific issue.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "issueId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Issue details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" }, "example": { "id": "iss_abc123", "title": "Pod not ready", "description": "Pod nginx-xyz in namespace default is not ready. Check container status and events.", "severity": 2, "observedAt": "2024-03-10T14:30:00Z", "slxName": "k8s-pod-health" } } } } } }, "patch": { "summary": "Update issue", "description": "Update issue state or metadata (e.g. acknowledge, resolve).", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "issueId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated issue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issue" } } } } } } }, "/api/v3/workspaces/{workspace}/slxs/": { "get": { "summary": "List SLXs", "description": "List all SLXs (Service Level Expectations) in a workspace.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of SLXs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SLXList" }, "example": { "slxs": [ { "name": "k8s-pod-health", "alias": "Pod Health Check", "statement": "All pods should be running", "intervalSeconds": 300 } ] } } } } } } }, "/api/v3/workspaces/{workspace}/slxs/{slxName}/": { "get": { "summary": "Get SLX detail", "description": "Retrieve detailed information about a specific SLX.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slxName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SLX details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SLX" } } } } } } }, "/api/v3/workspaces/{workspace}/run-sessions/": { "get": { "summary": "List run sessions", "description": "List run sessions for the workspace with optional pagination.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "RUNNING", "SUCCEEDED", "FAILED" ] } } ], "responses": { "200": { "description": "Paginated list of run sessions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSessionList" } } } } } }, "post": { "summary": "Create run session", "description": "Create and start a new run session for an SLX.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSessionCreateRequest" }, "example": { "slxName": "k8s-pod-health", "location": "northamerica-northeast2-01", "envVars": { "NAMESPACE": "default" } } } } }, "responses": { "201": { "description": "Run session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSession" }, "example": { "id": "run_xyz789", "slxName": "k8s-pod-health", "status": "RUNNING", "createdAt": "2024-03-10T15:00:00Z", "completedAt": null } } } } } } }, "/api/v3/workspaces/{workspace}/": { "get": { "summary": "Get workspace", "description": "Retrieve workspace details, configuration, health, and status.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } } } } }, "/api/v3/workspaces/{workspace}/run-sessions/{sessionId}/": { "get": { "summary": "Get run session", "description": "Retrieve status and details of a run session.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSession" }, "example": { "id": "run_xyz789", "slxName": "k8s-pod-health", "status": "SUCCEEDED", "createdAt": "2024-03-10T15:00:00Z", "completedAt": "2024-03-10T15:00:45Z" } } } } } } }, "/api/v3/workspaces/{workspace}/run-sessions/{sessionId}/run-requests/": { "get": { "summary": "List run requests", "description": "List run requests (task executions) for a run session.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated list of run requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequestList" } } } } } } }, "/api/v3/workspaces/{workspace}/run-sessions/{sessionId}/run-requests/{requestId}/": { "get": { "summary": "Get run request", "description": "Retrieve status and output for a single run request.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run request details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } } } } } }, "/api/v3/workspaces/{workspace}/slxs/{slxName}/slis/": { "get": { "summary": "List SLIs", "description": "List SLIs (Service Level Indicators) for an SLX.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slxName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of SLIs", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SLI" } } } } } } } } } }, "/api/v3/workspaces/{workspace}/slxs/{slxName}/slos/": { "get": { "summary": "List SLOs", "description": "List SLOs (Service Level Objectives) for an SLX.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slxName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of SLOs", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SLO" } } } } } } } } } }, "/api/v3/workspaces/{workspace}/slxs/{slxName}/runbooks/": { "get": { "summary": "List runbooks", "description": "List runbooks associated with an SLX.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "slxName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of runbooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Runbook" } } } } } } } } } }, "/api/v3/workspaces/{workspace}/workflows/": { "get": { "summary": "List workflows", "description": "List automation workflows for the workspace.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated list of workflows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowList" } } } } } } }, "/api/v3/workspaces/{workspace}/workflows/{workflowId}/": { "get": { "summary": "Get workflow", "description": "Retrieve workflow configuration and status.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } } } } }, "/api/v3/workspaces/{workspace}/workflows/{workflowId}/trigger/": { "post": { "summary": "Trigger workflow", "description": "Trigger workflow execution with an optional payload.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerRequest" } } } }, "responses": { "202": { "description": "Workflow triggered", "content": { "application/json": { "schema": { "type": "object", "properties": { "executionId": { "type": "string" }, "status": { "type": "string" } } } } } } } } }, "/api/v3/workspaces/{workspace}/personas/": { "get": { "summary": "List personas", "description": "List AI personas configured for the workspace.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated list of personas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonaList" } } } } } } }, "/api/v3/workspaces/{workspace}/personas/{personaId}/": { "get": { "summary": "Get persona", "description": "Retrieve persona configuration and assistant settings.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "personaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Persona details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Persona" } } } } } } }, "/api/v3/workspaces/{workspace}/code-collections/": { "get": { "summary": "List code collections", "description": "List code collections (repositories/branches) available in the workspace.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated list of code collections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeCollectionList" } } } } } } }, "/api/v3/workspaces/{workspace}/code-collections/{codeCollectionId}/": { "get": { "summary": "Get code collection", "description": "Retrieve code collection metadata and ref.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codeCollectionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Code collection details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeCollection" } } } } } } }, "/api/v3/workspaces/{workspace}/code-collections/{codeCollectionId}/codebundles/": { "get": { "summary": "List codebundles", "description": "List codebundles in a code collection with metadata and statistics.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codeCollectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated list of codebundles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodebundleList" } } } } } } }, "/api/v3/workspaces/{workspace}/code-collections/{codeCollectionId}/codebundles/{codebundleName}/": { "get": { "summary": "Get codebundle", "description": "Retrieve codebundle metadata and statistics.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codeCollectionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codebundleName", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Codebundle details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Codebundle" } } } } } } }, "/api/v3/users/me/": { "get": { "summary": "Current user", "description": "Retrieve the authenticated user profile.", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } } } }, "/api/v3/users/": { "get": { "summary": "List users", "description": "List or search users (e.g. workspace members).", "parameters": [ { "name": "workspace", "in": "query", "schema": { "type": "string", "description": "Filter by workspace" } }, { "name": "q", "in": "query", "schema": { "type": "string", "description": "Search query" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Paginated list of users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserList" } } } } } } }, "/api/v3/workspaces/{workspace}/task-search/": { "post": { "summary": "Task search", "description": "Semantic search over tasks (codebundles/SLXs) in the workspace.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSearchRequest" } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskSearchResultList" } } } } } } }, "/api/v3/workspaces/{workspace}/activities/": { "get": { "summary": "List activities", "description": "List workspace activity (runs, changes, events) with optional filters.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "type", "in": "query", "schema": { "type": "string", "description": "Filter by activity type" } } ], "responses": { "200": { "description": "Paginated list of activities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityList" } } } } } } }, "/api/v3/workspaces/{workspace}/chat-config/rules": { "get": { "tags": [ "Rules" ], "summary": "List chat rules", "description": "List rules for a workspace. Omitting scope_type returns workspace + persona + the caller's own user-scope rules.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "scope_type", "in": "query", "schema": { "type": "string", "enum": [ "workspace", "persona", "user" ] } }, { "name": "scope_id", "in": "query", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Paginated rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList" } } } } } }, "post": { "tags": [ "Rules" ], "summary": "Create a chat rule", "description": "Create a rule. Workspace and persona scopes require workspace admin; user scope is self-owned.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleCreate" } } } }, "responses": { "201": { "description": "Rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } } }, "403": { "description": "Workspace admin required for workspace/persona scope" } } } }, "/api/v3/workspaces/{workspace}/chat-config/rules/{ruleId}": { "get": { "tags": [ "Rules" ], "summary": "Get a chat rule", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Rule identifier" } ], "responses": { "200": { "description": "Rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } } }, "404": { "description": "Rule not found" } } }, "put": { "tags": [ "Rules" ], "summary": "Update a chat rule", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Rule identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleUpdate" } } } }, "responses": { "200": { "description": "Updated rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rule" } } } }, "404": { "description": "Rule not found" } } }, "delete": { "tags": [ "Rules" ], "summary": "Delete a chat rule", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Rule identifier" } ], "responses": { "204": { "description": "Rule deleted" }, "404": { "description": "Rule not found" } } } }, "/api/v3/workspaces/{workspace}/chat-config/commands": { "get": { "tags": [ "Commands" ], "summary": "List chat commands", "description": "List slash-commands for a workspace. Omitting scope_type returns workspace + persona + the caller's own user-scope commands.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "scope_type", "in": "query", "schema": { "type": "string", "enum": [ "workspace", "persona", "user" ] } }, { "name": "scope_id", "in": "query", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } } ], "responses": { "200": { "description": "Paginated commands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedList" } } } } } }, "post": { "tags": [ "Commands" ], "summary": "Create a chat command", "description": "Create a slash-command. Set cron_schedule to run the command on a schedule and deliver artifacts to sink_configs.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandCreate" } } } }, "responses": { "201": { "description": "Command created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" } } } }, "403": { "description": "Workspace admin required for workspace/persona scope" } } } }, "/api/v3/workspaces/{workspace}/chat-config/commands/{commandId}": { "get": { "tags": [ "Commands" ], "summary": "Get a chat command", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "commandId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Command identifier" } ], "responses": { "200": { "description": "Command", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" } } } }, "404": { "description": "Command not found" } } }, "put": { "tags": [ "Commands" ], "summary": "Update a chat command", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "commandId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Command identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandUpdate" } } } }, "responses": { "200": { "description": "Updated command", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Command" } } } }, "404": { "description": "Command not found" } } }, "delete": { "tags": [ "Commands" ], "summary": "Delete a chat command", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "commandId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Command identifier" } ], "responses": { "204": { "description": "Command deleted" }, "404": { "description": "Command not found" } } } }, "/api/v3/workspaces/{workspace}/chat-config/commands/{commandId}/run-now": { "post": { "tags": [ "Commands" ], "summary": "Run a command now", "description": "Trigger an immediate run of a scheduled command outside its cron schedule. Returns 202 Accepted.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "commandId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Command identifier" } ], "responses": { "202": { "description": "Run accepted" } } } }, "/api/v3/workspaces/{workspace}/chat-config/resolved": { "get": { "tags": [ "Rules" ], "summary": "Get resolved chat configuration", "description": "Return the fully resolved rules and commands an assistant will load for a workspace (and optional persona), after scope merging.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "persona_name", "in": "query", "schema": { "type": "string" }, "description": "Resolve for a specific persona" } ], "responses": { "200": { "description": "Resolved configuration" } } } }, "/api/v4/workspaces/{workspace}/personas": { "get": { "tags": [ "Assistants" ], "summary": "List assistants (personas)", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "responses": { "200": { "description": "Assistants", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Assistant" } } } } } } } }, "/api/v4/workspaces/{workspace}/personas/{personaShortName}": { "get": { "tags": [ "Assistants" ], "summary": "Get an assistant", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "personaShortName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Assistant short name" } ], "responses": { "200": { "description": "Assistant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assistant" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Assistants" ], "summary": "Delete an assistant", "description": "Soft-deletes the assistant. Persona-scoped rules and commands are NOT removed automatically.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "personaShortName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Assistant short name" } ], "responses": { "200": { "description": "Deleted" }, "204": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/api/v4/workspaces/{workspace}/personas/sync-typed": { "post": { "tags": [ "Assistants" ], "summary": "Create or update an assistant (upsert)", "description": "Full upsert of an assistant by name. Omitted fields reset to defaults \u2014 read the current persona and merge for partial updates. After creating, attach behavior with persona-scoped Rules and Commands (scope_type=persona, scope_id=shortName).", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantSyncRequest" } } } }, "responses": { "200": { "description": "Upserted assistant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assistant" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assistant" } } } } } } }, "/api/v3/workspaces/{workspace}/author/run": { "post": { "tags": [ "Tool Builder" ], "summary": "Execute a script on a runner (test)", "description": "Run a task/SLI script on the workspace runner for testing. Returns a run_id to poll. This is the API behind the MCP run_script tool.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorRunCreate" } } } }, "responses": { "200": { "description": "Run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorRunResponse" } } } }, "202": { "description": "Run accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorRunResponse" } } } } } } }, "/api/v3/workspaces/{workspace}/author/run/{runId}/status": { "get": { "tags": [ "Tool Builder" ], "summary": "Get author run status", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run identifier" } ], "responses": { "200": { "description": "Run status (RUNNING, SUCCEEDED, FAILED)" } } } }, "/api/v3/workspaces/{workspace}/author/run/{runId}/output": { "get": { "tags": [ "Tool Builder" ], "summary": "Get author run output", "description": "Parsed output of a completed run \u2014 issues, stdout, stderr, report.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Run identifier" } ], "responses": { "200": { "description": "Run output" } } } }, "/api/v1/workspaces/{workspace}/slxs/sync": { "post": { "tags": [ "Custom Tasks" ], "summary": "Create or update an SLX (upsert)", "description": "Upsert an SLX. Commit a custom task by syncing the SLX, then its Runbook (POST /runbooks/sync) and optional SLI (POST /slis/sync). Prefer the MCP Tool Builder (commit_slx) which validates and tests first. See the GitOps guide.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest" } } } }, "responses": { "200": { "description": "Upserted SLX (returns resource_id)" }, "201": { "description": "Created" } } } }, "/api/v1/workspaces/{workspace}/runbooks/sync": { "post": { "tags": [ "Custom Tasks" ], "summary": "Create or update an SLX Runbook (upsert)", "description": "Upsert the Runbook (tasks) for an SLX. The payload's slx_id ties it to a previously synced SLX.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest" } } } }, "responses": { "200": { "description": "Upserted runbook" }, "201": { "description": "Created" } } } }, "/api/v1/workspaces/{workspace}/slis/sync": { "post": { "tags": [ "Custom Tasks" ], "summary": "Create or update an SLX SLI (upsert)", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest" } } } }, "responses": { "200": { "description": "Upserted SLI" }, "201": { "description": "Created" } } } }, "/api/v4/workspaces/{workspace}/slxs/{slxShortName}": { "delete": { "tags": [ "Custom Tasks" ], "summary": "Delete an SLX", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "slxShortName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SLX short name" } ], "responses": { "200": { "description": "Deleted" }, "204": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/api/v3/workspaces/{workspace}/secrets-keys": { "get": { "tags": [ "Workspace Configuration" ], "summary": "List workspace secret keys", "description": "List available secret key names (not values) for mapping into tasks via secretVars.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "responses": { "200": { "description": "Secret key names" } } } }, "/api/v3/workspaces/{workspace}/runners": { "get": { "tags": [ "Workspace Configuration" ], "summary": "List runner locations", "description": "Runner locations where scripts/tasks can execute (used as the `location` for author runs and runbooks). Each location includes heartbeat-derived `health` and, per codebundle worker pool, live worker health and throughput under `workerPools`.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "responses": { "200": { "description": "Runner locations with per-pool worker status", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuthorizedRunner" } } } } } } } }, "/api/v3/workspaces/{workspace}/workspace-configuration-index": { "get": { "tags": [ "Workspace Configuration" ], "summary": "Get the workspace configuration index", "description": "Full workspace configuration overview \u2014 resources, SLXs, and their relationships (Sobow index).", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "responses": { "200": { "description": "Configuration index" } } } }, "/api/v3/workspaces/{workspace}/autocomplete": { "post": { "tags": [ "Workspace Configuration" ], "summary": "Autocomplete search", "description": "Lightweight keyword autocomplete over tasks, resources, and configuration. For richer results use workspace chat.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Search results" } } } }, "/api/v3/workspaces/{workspace}/runner-token": { "get": { "tags": [ "Workspace Configuration" ], "summary": "Get a runner registration token", "description": "Generate a registration token used to enroll a new runner at a given location. Requires the workspace **admin** role. The runner (RunWhen Local / runner-control) uses the returned token to register and obtain its upload/config credentials.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Location name for the runner (becomes the runner identity {workspace}--{location})" } ], "responses": { "200": { "description": "Runner registration token + registration details" }, "403": { "description": "Admin permission required" }, "404": { "description": "Workspace not found" }, "422": { "description": "Missing location or runner request failed" }, "503": { "description": "Runner service unavailable" } } } }, "/api/v4/workspaces/{workspace}/notes": { "get": { "tags": [ "Knowledge Base" ], "summary": "List Knowledge Base notes", "description": "List notes for a workspace. view=full (default) returns notes with content. view=summary returns a lightweight metadata-only representation. includeEnrichment=true wraps the response with USearch indexing metadata (incompatible with view=summary).", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "view", "in": "query", "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full" }, "description": "\"full\": notes with content. \"summary\": metadata-only (no content body)." }, { "name": "includeEnrichment", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include USearch indexing metadata (returns a paginated wrapper \u2014 incompatible with view=summary)" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "deprecated" ] }, "description": "Filter by lifecycle status" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring filter on title (and content in full view)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 200, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Array of notes (full or summary) or paginated enriched response" } } }, "post": { "tags": [ "Knowledge Base" ], "summary": "Create a Knowledge Base note", "description": "Create a note. Leave resourcePaths empty for a global note, or set them to scope the note to specific resources. Use resourceSelectors with tag matchTags to attach the note to every resource carrying a given tag.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreateV4" } } } }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponseV4" } } } } } }, "delete": { "tags": [ "Knowledge Base" ], "summary": "Delete KB notes from a source", "description": "Batch-delete notes from one source by sourceIds. dryRun=true previews without deleting. Requires workspace admin.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteDeleteRequestV4" } } } }, "responses": { "200": { "description": "Delete results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteDeleteResponseV4" } } } } } } }, "/api/v4/workspaces/{workspace}/notes/{noteId}": { "get": { "tags": [ "Knowledge Base" ], "summary": "Get a note", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Note identifier (UUID)" } ], "responses": { "200": { "description": "Note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponseV4" } } } }, "404": { "description": "Note not found" } } }, "patch": { "tags": [ "Knowledge Base" ], "summary": "Update a note", "description": "Partial update \u2014 omitted fields are left unchanged. Externally-synced notes (sourceKind != manual) are read-only and return 409.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Note identifier (UUID)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdateV4" } } } }, "responses": { "200": { "description": "Updated note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponseV4" } } } }, "404": { "description": "Note not found" }, "409": { "description": "Note is externally owned \u2014 edit at source" } } }, "delete": { "tags": [ "Knowledge Base" ], "summary": "Delete a note", "description": "Delete a manually-authored note. Externally-synced notes return 409.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Note identifier (UUID)" } ], "responses": { "204": { "description": "Note deleted" }, "404": { "description": "Note not found" }, "409": { "description": "Note is externally owned \u2014 delete at source" } } } }, "/api/v4/workspaces/{workspace}/notes/sync": { "post": { "tags": [ "Knowledge Base" ], "summary": "Publish (upsert) a KB note from an external source", "description": "Upsert a note identified by its sourceKind/source/sourceId. The content is the full markdown note with YAML frontmatter. dryRun=true validates without writing. Requires workspace admin. Synced notes become read-only in the CRUD API.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteSyncRequestV4" } } } }, "responses": { "200": { "description": "Sync result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteSyncResponseV4" } } } } } } }, "/api/v4/workspaces/{workspace}/resource-paths": { "get": { "tags": [ "Knowledge Base" ], "summary": "List the workspace's valid resource paths", "description": "Resource paths to author and validate resourcePaths against.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "responses": { "200": { "description": "List of resource paths", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourcePathsResponseV4" } } } } } } }, "/api/v4/workspaces/{workspace}/tags": { "get": { "tags": [ "Knowledge Base" ], "summary": "List the workspace's tag keys and values", "description": "Tag keys and sample values to author matchTags selectors against. Keys carry provider prefixes ([k8s]..., [aws]...).", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "limitValues", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 }, "description": "Max sample values returned per tag key" } ], "responses": { "200": { "description": "Tag keys and values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTagsResponseV4" } } } } } } }, "/api/v1/workspaces/{workspace}/chat-pro-sse": { "post": { "tags": [ "Workspace Chat" ], "summary": "Start or continue a workspace chat (SSE)", "description": "Stream an AI investigation turn as Server-Sent Events. This is the endpoint the RunWhen UI and MCP `workspace_chat` tool use. Set `sessionId` to null on the first turn; reuse the `sessionId` from the response stream on follow-ups. To invoke a saved slash-command programmatically, set `message` to a markdown link `[command-name](http://chat-command/{commandId})` \u2014 the same format the UI sends.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceChatRequest" } } } }, "responses": { "200": { "description": "SSE stream of ChatSseEvent JSON objects", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Server-Sent Events stream. Each event is a `data:` line containing JSON matching ChatSseEvent. The first frames include `sessionId` when a new session is created." } } } }, "400": { "description": "Invalid userId (must be email) or request body" }, "401": { "description": "Missing or invalid Bearer token" } }, "servers": [ { "url": "https://agentfarm.{domain}", "description": "AgentFarm \u2014 AI orchestration for workspace chat. Same domain variable as PAPI (SaaS: beta.runwhen.com; self-hosted: global.domain).", "variables": { "domain": { "default": "beta.runwhen.com", "description": "Your RunWhen domain." } } } ] } }, "/api/v1/workspaces/{workspace}/chat/{sessionId}/abort": { "post": { "tags": [ "Workspace Chat" ], "summary": "Abort an in-flight chat turn", "description": "Stop the current streaming turn for `sessionId`. Idempotent \u2014 returns 202 even if the turn already finished. The body `userId` must match the session owner.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Chat session id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbortChatRequest" } } } }, "responses": { "202": { "description": "Abort signal published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbortChatResponse" } } } }, "404": { "description": "Session not found for this workspace and userId" } }, "servers": [ { "url": "https://agentfarm.{domain}", "description": "AgentFarm \u2014 AI orchestration for workspace chat. Same domain variable as PAPI (SaaS: beta.runwhen.com; self-hosted: global.domain).", "variables": { "domain": { "default": "beta.runwhen.com", "description": "Your RunWhen domain." } } } ] } }, "/api/v1/workspaces/{workspace}/chat-export-url": { "post": { "tags": [ "Workspace Chat" ], "summary": "Create a read-only chat export URL", "description": "Return a signed relative URL (`exportUrl`) for sharing a completed chat session. Idempotent while the latest link is still valid.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatExportUrlRequest" } } } }, "responses": { "200": { "description": "Export link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatExportUrlResponse" } } } }, "404": { "description": "Session not found" } }, "servers": [ { "url": "https://agentfarm.{domain}", "description": "AgentFarm \u2014 AI orchestration for workspace chat. Same domain variable as PAPI (SaaS: beta.runwhen.com; self-hosted: global.domain).", "variables": { "domain": { "default": "beta.runwhen.com", "description": "Your RunWhen domain." } } } ] } }, "/api/v3/workspaces/{workspace}/service-account-tokens": { "get": { "tags": [ "Service Account Tokens" ], "summary": "List service account tokens", "description": "List admin-managed API tokens scoped to this workspace. Caller must be a workspace **admin**.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Token list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountTokenList" } } } } } }, "post": { "tags": [ "Service Account Tokens" ], "summary": "Create a service account token", "description": "Create a dedicated service-account user scoped to this workspace and return a JWT (`token` field) usable as `Authorization: Bearer ` on PAPI and AgentFarm. The full token is returned once \u2014 store it securely. Caller must be a workspace **admin**.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountTokenCreate" } } } }, "responses": { "201": { "description": "Token created (includes one-time JWT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountTokenCreateResponse" } } } }, "403": { "description": "Admin permission required" }, "404": { "description": "Workspace not found" } } } }, "/api/v3/workspaces/{workspace}/service-account-tokens/{tokenId}": { "get": { "tags": [ "Service Account Tokens" ], "summary": "Get a service account token", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Token UUID" } ], "responses": { "200": { "description": "Token metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountToken" } } } }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Service Account Tokens" ], "summary": "Delete a service account token", "description": "Permanently deletes the token, its scopes, and the backing service-account user.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Token UUID" } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/api/v3/workspaces/{workspace}/service-account-tokens/{tokenId}/revoke": { "post": { "tags": [ "Service Account Tokens" ], "summary": "Revoke a service account token", "description": "Marks the token revoked. The JWT is rejected immediately; the row is retained for audit.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Token UUID" } ], "responses": { "200": { "description": "Revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountToken" } } } }, "404": { "description": "Not found" } } } }, "/api/v3/workspaces/{workspace}/service-account-tokens/{tokenId}/scopes": { "put": { "tags": [ "Service Account Tokens" ], "summary": "Replace token workspace scopes", "description": "Replace all workspace scopes on the token. At least one scope is required. Caller must be admin of every workspace in the new scope set and of any workspace being removed.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Token UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ServiceAccountTokenScopeUpdate" } } } } }, "responses": { "200": { "description": "Updated token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountToken" } } } }, "400": { "description": "Invalid scopes" } } } }, "/api/v3/workspaces/{workspace}/service-account-tokens/{tokenId}/scopes/{workspaceId}": { "delete": { "tags": [ "Service Account Tokens" ], "summary": "Remove one workspace scope from a token", "description": "Cannot remove the last remaining scope.", "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace short name" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Token UUID" }, { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Workspace primary key" } ], "responses": { "200": { "description": "Updated token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccountToken" } } } }, "400": { "description": "Cannot remove last scope" } } } } }, "tags": [ { "name": "Knowledge Base", "description": "Knowledge Base notes \u2014 institutional context loaded into AI Assistant investigations." }, { "name": "Rules", "description": "Chat rules \u2014 instructions loaded into assistant prompt context to shape interpretation." }, { "name": "Commands", "description": "Chat commands (slash-commands) \u2014 repeatable investigation procedures, on demand or scheduled." }, { "name": "Assistants", "description": "AI Assistants (personas) \u2014 create, configure, and delete the assistants that drive investigations." }, { "name": "Tool Builder", "description": "Author and test custom task/SLI scripts on a runner before committing them as SLXs." }, { "name": "Custom Tasks", "description": "Commit custom tasks as SLXs (SLX/Runbook/SLI sync) and delete them." }, { "name": "Workspace Configuration", "description": "Supporting reads: secret keys, runner locations, configuration index, and autocomplete." }, { "name": "Service Account Tokens", "description": "Admin-managed JWT credentials for automation and integrations. Distinct from the built-in per-workspace `{workspace}-sa` service account (obtain that token via POST /api/v3/token/ with the SA username and password)." }, { "name": "Workspace Chat", "description": "AgentFarm streaming chat API \u2014 programmatic equivalent of Workspace Chat in the UI and the MCP workspace_chat tool." } ] }