openapi: 3.1.0
info:
  title: RunAgents API
  version: v1alpha
  summary: Target programmatic REST API contract for RunAgents.
  description: 'This OpenAPI document is the target machine-readable contract for
    the RunAgents programmatic API. It is the source contract for generated SDK, CLI,
    and assistant-facing integrations where coverage exists. Tenant and workspace
    context are carried by the base URL. Workspace API keys are sent with the X-RunAgents-API-Key
    header. Connected identity-provider JWTs remain bearer tokens for end-user agent/runtime
    flows. Kubernetes namespaces are an internal implementation detail and are not
    part of this public contract.

    '
servers:
- url: https://{trialId}.try.runagents.io/api/v1
  description: Trial host with one default workspace.
  variables:
    trialId:
      default: 1406e38143ac0e57
      description: Trial workspace host id.
- url: https://{company}.runagents.io/api/v1
  description: Company host using the caller token's default workspace.
  variables:
    company:
      default: acme
      description: Company tenant slug.
- url: https://{company}.runagents.io/api/v1/workspaces/{workspace}
  description: Company host with an explicit workspace in the base URL.
  variables:
    company:
      default: acme
      description: Company tenant slug.
    workspace:
      default: revops
      description: Workspace slug inside the company tenant.
security:
- workspaceApiKey: []
tags:
- name: Tools
  description: External tool registration and probing.
paths:
  /tools:
    get:
      tags:
      - Tools
      summary: List tools
      responses:
        '200':
          description: Registered tools.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tool'
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getTools
    post:
      tags:
      - Tools
      summary: Create or update a tool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolCreateRequest'
      responses:
        '201':
          description: Tool created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: postTools
  /tools/{toolName}:
    get:
      tags:
      - Tools
      summary: Get tool details
      parameters:
      - $ref: '#/components/parameters/ToolName'
      responses:
        '200':
          description: Tool details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: getToolsByToolName
    delete:
      tags:
      - Tools
      summary: Delete a tool
      parameters:
      - $ref: '#/components/parameters/ToolName'
      responses:
        '200':
          description: Tool deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: deleteToolsByToolName
  /tools/probe:
    post:
      tags:
      - Tools
      summary: Probe a URL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProbeRequest'
      responses:
        '200':
          description: Probe result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProbeResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: postToolsProbe
  /tools/{toolName}/test:
    post:
      tags:
      - Tools
      summary: Test a registered tool
      parameters:
      - $ref: '#/components/parameters/ToolName'
      responses:
        '200':
          description: Tool reachability result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProbeResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      operationId: postToolsByToolNameTest
components:
  securitySchemes:
    workspaceApiKey:
      type: apiKey
      in: header
      name: X-RunAgents-API-Key
      description: 'Workspace API key for programmatic control-plane access. Use this
        header for tokens with the ra_ws_ prefix. Do not send workspace keys as Authorization
        bearer tokens on hosted trial or company URLs; bearer Authorization is reserved
        for connected OIDC/JWT identity flows.

        '
  parameters:
    RequestId:
      name: requestId
      in: path
      required: true
      schema:
        type: string
    RunId:
      name: runId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ActionId:
      name: actionId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    KeyId:
      name: keyId
      in: path
      required: true
      schema:
        type: string
    CatalogId:
      name: catalogId
      in: path
      required: true
      schema:
        type: string
    PolicyName:
      name: policyName
      in: path
      required: true
      schema:
        type: string
    ConnectorId:
      name: connectorId
      in: path
      required: true
      schema:
        type: string
    ProviderName:
      name: providerName
      in: path
      required: true
      schema:
        type: string
    AgentName:
      name: agentName
      in: path
      required: true
      schema:
        type: string
    ToolName:
      name: toolName
      in: path
      required: true
      schema:
        type: string
    BuildId:
      name: buildId
      in: path
      required: true
      schema:
        type: string
    DraftId:
      name: draftId
      in: path
      required: true
      schema:
        type: string
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Authenticated caller cannot access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: State transition conflict or payload mismatch.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadGateway:
      description: Upstream provider or agent request failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    DeleteStatus:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - deleted
    ApprovalStatus:
      type: string
      enum:
      - PENDING
      - APPROVED
      - REJECTED
      - EXPIRED
    ApprovalScope:
      type: string
      enum:
      - once
      - run
      - agent_user_ttl
    AccessRequest:
      type: object
      required:
      - id
      - status
      properties:
        id:
          type: string
        subject:
          type: string
        agent_id:
          type: string
        tool_id:
          type: string
        status:
          $ref: '#/components/schemas/ApprovalStatus'
        duration:
          type: string
        scope:
          $ref: '#/components/schemas/ApprovalScope'
        approver_id:
          type: string
        reason:
          type: string
        action_id:
          type: string
        run_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
    CreateAccessRequest:
      type: object
      required:
      - subject
      - tool_id
      properties:
        subject:
          type: string
        tool_id:
          type: string
        agent_id:
          type: string
        duration:
          type: string
        run_id:
          type: string
          format: uuid
        capability:
          type: string
        payload_hash:
          type: string
        tool_method:
          type: string
        tool_url:
          type: string
          format: uri
    ApprovalDecision:
      type: object
      properties:
        scope:
          $ref: '#/components/schemas/ApprovalScope'
        duration:
          type: string
        reason:
          type: string
    RejectionDecision:
      type: object
      properties:
        reason:
          type: string
    RunStatus:
      type: string
      enum:
      - RUNNING
      - PAUSED
      - PAUSED_APPROVAL
      - PAUSED_CONSENT
      - COMPLETED
      - FAILED
    Run:
      type: object
      required:
      - id
      - agent_id
      - user_id
      - status
      - created_at
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        conversation_id:
          type: string
        agent_id:
          type: string
        namespace:
          type: string
        user_id:
          type: string
        invoke_url:
          type: string
          format: uri
        status:
          $ref: '#/components/schemas/RunStatus'
        blocked_action_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateRun:
      type: object
      required:
      - agent_id
      - user_id
      properties:
        agent_id:
          type: string
        user_id:
          type: string
        conversation_id:
          type: string
        invoke_url:
          type: string
          format: uri
    UpdateRunStatus:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - COMPLETED
          - FAILED
          - PAUSED_APPROVAL
          - RUNNING
    RunEventType:
      type: string
      enum:
      - USER_MESSAGE
      - AGENT_MESSAGE
      - TOOL_REQUEST
      - TOOL_RESPONSE
      - APPROVAL_REQUIRED
      - CONSENT_REQUIRED
      - APPROVED
      - REJECTED
      - RESUMED
      - RUN_CREATED
      - INVOKE_REQUESTED
      - INVOKE_COMPLETED
      - INVOKE_FAILED
      - TOOL_CALLED
      - COMPLETED
      - FAILED
    RunEvent:
      type: object
      required:
      - event_id
      - run_id
      - seq
      - type
      - timestamp
      properties:
        event_id:
          type: string
        run_id:
          type: string
          format: uuid
        seq:
          type: integer
        type:
          $ref: '#/components/schemas/RunEventType'
        actor:
          type: string
        payload_hash:
          type: string
        timestamp:
          type: string
          format: date-time
    CreateRunEvent:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/RunEventType'
        payload_hash:
          type: string
        actor:
          type: string
    ActionStatus:
      type: string
      enum:
      - BLOCKED
      - APPROVED
      - EXECUTED
      - FAILED
      - EXPIRED
    BlockedAction:
      type: object
      required:
      - action_id
      - run_id
      - tool_id
      - status
      - created_at
      - updated_at
      properties:
        action_id:
          type: string
          format: uuid
        run_id:
          type: string
          format: uuid
        tool_id:
          type: string
        capability:
          type: string
        payload_hash:
          type: string
        status:
          $ref: '#/components/schemas/ActionStatus'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateBlockedAction:
      type: object
      required:
      - tool_id
      properties:
        tool_id:
          type: string
        capability:
          type: string
        payload_hash:
          type: string
    ApproveBlockedAction:
      type: object
      properties:
        payload_hash:
          type: string
    CatalogEntry:
      type: object
      required:
      - id
      - name
      - summary
      properties:
        id:
          type: string
        name:
          type: string
        summary:
          type: string
        category:
          type: string
        tags:
          type: array
          items:
            type: string
        latest_version:
          type: string
        required_integrations:
          type: array
          items:
            type: string
        governance_traits:
          type: array
          items:
            type: string
        complexity:
          type: string
    CatalogListResponse:
      type: object
      required:
      - generated_at
      - items
      - total
      - page
      - page_size
      properties:
        generated_at:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/CatalogEntry'
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
    CatalogDeploymentTemplate:
      type: object
      properties:
        agentName:
          type: string
        systemPrompt:
          type: string
        requiredTools:
          type: array
          items:
            type: string
        policies:
          type: array
          items:
            type: string
        identityProvider:
          type: string
        sourceType:
          type: string
        sourceFiles:
          type: object
          additionalProperties:
            type: string
    CatalogManifest:
      type: object
      required:
      - id
      - version
      - name
      - summary
      properties:
        id:
          type: string
        version:
          type: string
        name:
          type: string
        summary:
          type: string
        defaultModel:
          type: string
        requiredIntegrations:
          type: array
          items:
            type: string
        governanceTraits:
          type: array
          items:
            type: string
        deploymentTemplate:
          $ref: '#/components/schemas/CatalogDeploymentTemplate'
    CatalogVersion:
      type: object
      required:
      - version
      - published_at
      properties:
        version:
          type: string
        published_at:
          type: string
          format: date-time
        summary:
          type: string
        changelog:
          type: string
    CatalogVersionsResponse:
      type: object
      required:
      - agent_id
      - versions
      properties:
        agent_id:
          type: string
        versions:
          type: array
          items:
            $ref: '#/components/schemas/CatalogVersion'
    DeployToolCreate:
      type: object
      required:
      - name
      - base_url
      properties:
        name:
          type: string
        base_url:
          type: string
          format: uri
        description:
          type: string
        auth_type:
          type: string
          enum:
          - None
          - APIKey
          - OAuth2
        port:
          type: integer
        scheme:
          type: string
          enum:
          - HTTP
          - HTTPS
    LlmConfig:
      type: object
      additionalProperties: true
    EnvVar:
      type: object
      additionalProperties: true
    DeployRequest:
      type: object
      required:
      - agent_name
      properties:
        agent_name:
          type: string
        image:
          type: string
        source_files:
          type: object
          additionalProperties:
            type: string
        artifact_id:
          type: string
        draft_id:
          type: string
        system_prompt:
          type: string
        required_tools:
          type: array
          items:
            type: string
        tool_url_mappings:
          type: object
          additionalProperties:
            type: string
        tools_to_create:
          type: array
          items:
            $ref: '#/components/schemas/DeployToolCreate'
        llm_configs:
          type: array
          items:
            $ref: '#/components/schemas/LlmConfig'
        env:
          type: array
          items:
            $ref: '#/components/schemas/EnvVar'
        requirements:
          type: string
        entry_point:
          type: string
        framework:
          type: string
        identity_provider:
          type: string
        policies:
          type: array
          items:
            type: string
    DeployResponse:
      type: object
      required:
      - agent
      - namespace
      properties:
        agent:
          type: string
        namespace:
          type: string
        tools_created:
          type: array
          items:
            type: string
        build_id:
          type: string
        image_uri:
          type: string
        execution_mode:
          type: string
        build_required:
          type: boolean
        build_profile:
          type: string
        decision_reason:
          type: string
    DeployDraftStatus:
      type: string
      enum:
      - IN_PROGRESS
      - COMPLETED
      - ABANDONED
    DeployDraftModelMapping:
      type: object
      required:
      - provider
      - model
      properties:
        provider:
          type: string
        model:
          type: string
        monthly_budget_usd:
          type: number
          format: double
    DeployDraftAgentConfig:
      type: object
      properties:
        agent_name:
          type: string
        system_prompt:
          type: string
        use_custom_image:
          type: boolean
        custom_image:
          type: string
        access_mode:
          type: string
          enum:
          - open
          - authenticated
        identity_provider:
          type: string
    DeployDraftInput:
      type: object
      properties:
        artifact_id:
          type: string
        source_type:
          type: string
        runtime_family:
          type: string
        adapter:
          type: string
        step:
          type: string
        policies:
          type: array
          items:
            type: string
        required_tool_names:
          type: array
          items:
            type: string
        recommended_tool_names:
          type: array
          items:
            type: string
        tool_mappings:
          type: object
          additionalProperties:
            type: string
        tool_states:
          type: object
          additionalProperties:
            type: string
        model_mappings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DeployDraftModelMapping'
        agent_config:
          $ref: '#/components/schemas/DeployDraftAgentConfig'
    DeployDraftPatch:
      allOf:
      - $ref: '#/components/schemas/DeployDraftInput'
      - type: object
        properties:
          expected_version:
            type: integer
          status:
            $ref: '#/components/schemas/DeployDraftStatus'
    DeployDraft:
      type: object
      required:
      - id
      - status
      - version
      - created_at
      - updated_at
      properties:
        id:
          type: string
        namespace:
          type: string
        user_id:
          type: string
        status:
          $ref: '#/components/schemas/DeployDraftStatus'
        step:
          type: string
        artifact_id:
          type: string
        source_type:
          type: string
        runtime_family:
          type: string
        adapter:
          type: string
        policies:
          type: array
          items:
            type: string
        required_tool_names:
          type: array
          items:
            type: string
        recommended_tool_names:
          type: array
          items:
            type: string
        tool_mappings:
          type: object
          additionalProperties:
            type: string
        tool_states:
          type: object
          additionalProperties:
            type: string
        model_mappings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DeployDraftModelMapping'
        agent_config:
          $ref: '#/components/schemas/DeployDraftAgentConfig'
        version:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    StarterKitResponse:
      type: object
      properties:
        tool_created:
          type: string
        model_provider_created:
          type: string
    DeployPreviewAdvancedDetails:
      type: object
      required:
      - execution_mode
      - build_required
      properties:
        execution_mode:
          type: string
        build_required:
          type: boolean
        build_profile:
          type: string
        decision_reason:
          type: string
        execution_kind:
          type: string
        support_level:
          type: string
    DeployPreviewResponse:
      type: object
      required:
      - user_state
      - state_label
      - eta_range
      - confidence
      - short_reason
      - advanced_details
      properties:
        user_state:
          type: string
          enum:
          - instant
          - preparing_runtime
          - compatibility_setup
        state_label:
          type: string
        eta_range:
          type: string
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        short_reason:
          type: string
        advanced_details:
          $ref: '#/components/schemas/DeployPreviewAdvancedDetails'
    ContextExportResponse:
      type: object
      required:
      - generated_at
      - namespace
      - resources
      properties:
        generated_at:
          type: string
          format: date-time
        namespace:
          type: string
        user_id:
          type: string
        resources:
          type: object
          additionalProperties: true
        errors:
          type: object
          additionalProperties:
            type: string
        meta:
          type: object
          additionalProperties: true
    ActionPlanRequest:
      type: object
      required:
      - actions
      additionalProperties: false
      properties:
        plan_id:
          type: string
        continue_on_error:
          type: boolean
        actions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ActionPlanAction'
    ActionPlanAction:
      type: object
      required:
      - type
      - idempotency_key
      additionalProperties: false
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - tool.upsert
          - model_provider.upsert
          - policy.upsert
          - deploy_draft.create_or_patch
          - deploy.execute
          - starter_kit.seed
        idempotency_key:
          type: string
          minLength: 1
        params:
          type: object
          additionalProperties: true
    ActionPlanValidationResponse:
      type: object
      required:
      - namespace
      - valid
      - results
      properties:
        plan_id:
          type: string
        namespace:
          type: string
        valid:
          type: boolean
        results:
          type: array
          items:
            $ref: '#/components/schemas/ActionPlanValidationResult'
    ActionPlanValidationResult:
      type: object
      required:
      - id
      - type
      - valid
      properties:
        id:
          type: string
        type:
          type: string
        idempotency_key:
          type: string
        valid:
          type: boolean
        errors:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
        resource_ref:
          type: string
    ActionPlanApplyResponse:
      type: object
      required:
      - namespace
      - applied
      - applied_count
      - failed_count
      - results
      properties:
        plan_id:
          type: string
        namespace:
          type: string
        applied:
          type: boolean
        applied_count:
          type: integer
          minimum: 0
        failed_count:
          type: integer
          minimum: 0
        results:
          type: array
          items:
            $ref: '#/components/schemas/ActionPlanApplyResult'
    ActionPlanApplyResult:
      type: object
      required:
      - id
      - type
      - status
      properties:
        id:
          type: string
        type:
          type: string
        idempotency_key:
          type: string
        status:
          type: string
          enum:
          - applied
          - failed
          - skipped
          - invalid
        resource_ref:
          type: string
        error:
          type: string
        output:
          type: object
          additionalProperties: true
    AuthSettings:
      type: object
      required:
      - sessionIdleTimeoutMinutes
      - minSessionIdleTimeoutMinutes
      - maxSessionIdleTimeoutMinutes
      - programmaticHeader
      - apiKeyPrefix
      - apiKeyCount
      properties:
        sessionIdleTimeoutMinutes:
          type: integer
        minSessionIdleTimeoutMinutes:
          type: integer
        maxSessionIdleTimeoutMinutes:
          type: integer
        programmaticHeader:
          type: string
        apiKeyPrefix:
          type: string
        apiKeyCount:
          type: integer
        oauthCallbackUrl:
          type: string
    UpdateAuthSettingsRequest:
      type: object
      required:
      - sessionIdleTimeoutMinutes
      properties:
        sessionIdleTimeoutMinutes:
          type: integer
    WorkspaceApiKey:
      type: object
      required:
      - id
      - name
      - prefix
      - last4
      - createdAt
      properties:
        id:
          type: string
        name:
          type: string
        prefix:
          type: string
        last4:
          type: string
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
    CreateWorkspaceApiKeyRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        expiresInDays:
          type: integer
          minimum: 1
    RotateWorkspaceApiKeyRequest:
      type: object
      properties:
        expiresInDays:
          type: integer
          minimum: 1
    CreateWorkspaceApiKeyResponse:
      type: object
      required:
      - key
      - token
      - header
      properties:
        key:
          $ref: '#/components/schemas/WorkspaceApiKey'
        token:
          type: string
        header:
          type: string
    PolicyRule:
      type: object
      properties:
        permission:
          type: string
        operations:
          type: array
          items:
            type: string
        resource:
          type: string
    PolicyApprovalDelivery:
      type: object
      properties:
        connectors:
          type: array
          items:
            type: string
        mode:
          type: string
        fallbackToUI:
          type: boolean
    PolicyApprovalBinding:
      type: object
      properties:
        name:
          type: string
        toolIds:
          type: array
          items:
            type: string
        approvers:
          type: object
          additionalProperties: true
        defaultDuration:
          type: string
        delivery:
          $ref: '#/components/schemas/PolicyApprovalDelivery'
    PolicySpec:
      type: object
      properties:
        policies:
          type: array
          items:
            $ref: '#/components/schemas/PolicyRule'
        approvals:
          type: array
          items:
            $ref: '#/components/schemas/PolicyApprovalBinding'
    PolicyStatus:
      type: object
      properties:
        ready:
          type: boolean
        message:
          type: string
    PolicyUse:
      type: object
      properties:
        name:
          type: string
        namespace:
          type: string
    Policy:
      type: object
      required:
      - name
      - spec
      properties:
        name:
          type: string
        namespace:
          type: string
        spec:
          $ref: '#/components/schemas/PolicySpec'
        status:
          $ref: '#/components/schemas/PolicyStatus'
        used_by:
          type: array
          items:
            $ref: '#/components/schemas/PolicyUse'
    PolicyUpsertRequest:
      type: object
      required:
      - name
      - spec
      properties:
        name:
          type: string
        spec:
          $ref: '#/components/schemas/PolicySpec'
    TranslatePolicyRequest:
      type: object
      required:
      - text
      properties:
        text:
          type: string
    TranslatePolicyResponse:
      type: object
      required:
      - rules
      properties:
        rules:
          type: array
          items:
            $ref: '#/components/schemas/PolicyRule'
    ApprovalConnectorType:
      type: string
      enum:
      - webhook
      - slack
      - teams
      - jira
      - pagerduty
    ApprovalConnector:
      type: object
      required:
      - id
      - name
      - endpoint
      - enabled
      properties:
        id:
          type: string
        name:
          type: string
        type:
          $ref: '#/components/schemas/ApprovalConnectorType'
        endpoint:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        enabled:
          type: boolean
        timeout_seconds:
          type: integer
        slack_security_mode:
          type: string
          enum:
          - compat
          - strict
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ApprovalConnectorCreate:
      type: object
      required:
      - name
      - endpoint
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/ApprovalConnectorType'
        endpoint:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        enabled:
          type: boolean
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 120
        slack_security_mode:
          type: string
          enum:
          - compat
          - strict
    ApprovalConnectorPatch:
      type: object
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/ApprovalConnectorType'
        endpoint:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        enabled:
          type: boolean
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 120
        slack_security_mode:
          type: string
          enum:
          - compat
          - strict
    ApprovalConnectorCheck:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        status:
          type: string
        message:
          type: string
        duration_ms:
          type: integer
    ApprovalConnectorTestRequest:
      type: object
      required:
      - endpoint
      properties:
        type:
          $ref: '#/components/schemas/ApprovalConnectorType'
        endpoint:
          type: string
        headers:
          type: object
          additionalProperties:
            type: string
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 120
        slack_security_mode:
          type: string
          enum:
          - compat
          - strict
    ApprovalConnectorTestResult:
      type: object
      properties:
        status:
          type: string
        connector_type:
          type: string
        endpoint:
          type: string
        checks:
          type: array
          items:
            $ref: '#/components/schemas/ApprovalConnectorCheck'
    ApprovalConnectorDefaults:
      type: object
      properties:
        default_delivery_mode:
          type: string
        default_fallback_to_ui:
          type: boolean
        default_timeout_seconds:
          type: integer
        min_timeout_seconds:
          type: integer
        max_timeout_seconds:
          type: integer
    ApprovalConnectorDefaultsUpdate:
      type: object
      properties:
        default_delivery_mode:
          type: string
        default_fallback_to_ui:
          type: boolean
        default_timeout_seconds:
          type: integer
    ApprovalConnectorActivity:
      type: object
      properties:
        id:
          type: string
        timestamp:
          type: string
          format: date-time
        event:
          type: string
        connector_id:
          type: string
        connector_name:
          type: string
        request_id:
          type: string
        decision:
          type: string
        status_code:
          type: integer
        duration_ms:
          type: integer
        message:
          type: string
    IdentityProviderSettings:
      type: object
      required:
      - issuer
      - jwksUri
      properties:
        issuer:
          type: string
          format: uri
        jwksUri:
          type: string
          format: uri
        audiences:
          type: array
          items:
            type: string
    IdentityProviderSpec:
      type: object
      required:
      - host
      - identityProvider
      - userIDClaim
      properties:
        host:
          type: string
        identityProvider:
          $ref: '#/components/schemas/IdentityProviderSettings'
        userIDClaim:
          type: string
        allowedDomains:
          type: array
          items:
            type: string
    IdentityProvider:
      type: object
      required:
      - name
      - spec
      properties:
        name:
          type: string
        namespace:
          type: string
        spec:
          $ref: '#/components/schemas/IdentityProviderSpec'
    IdentityProviderUpsertRequest:
      type: object
      required:
      - name
      - spec
      properties:
        name:
          type: string
        spec:
          $ref: '#/components/schemas/IdentityProviderSpec'
    SecretRef:
      type: object
      properties:
        name:
          type: string
    AgentToolRef:
      type: object
      properties:
        name:
          type: string
    NameValuePair:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    AgentStatus:
      type: object
      properties:
        phase:
          type: string
        message:
          type: string
    AgentSpec:
      type: object
      properties:
        image:
          type: string
        systemPrompt:
          type: string
        requiredTools:
          type: array
          items:
            $ref: '#/components/schemas/AgentToolRef'
        llmConfig:
          type: object
          additionalProperties: true
        env:
          type: array
          items:
            $ref: '#/components/schemas/NameValuePair'
    Agent:
      type: object
      required:
      - name
      - namespace
      properties:
        name:
          type: string
        namespace:
          type: string
        labels:
          type: object
          additionalProperties:
            type: string
        spec:
          $ref: '#/components/schemas/AgentSpec'
        status:
          $ref: '#/components/schemas/AgentStatus'
    AgentConfigLLM:
      type: object
      required:
      - model
      properties:
        role:
          type: string
          description: Model role, such as chat, embedding, classify, or reranking.
        model_provider:
          type: string
          description: Registered RunAgents model provider name.
        provider:
          type: string
          description: Underlying provider type, such as openai or anthropic.
        model:
          type: string
        monthly_budget_usd:
          type: number
          format: double
          minimum: 0
          description: Optional monthly budget for this agent/model mapping.
    AgentModelUsage:
      type: object
      required:
      - label
      - model
      - estimated_spend_usd
      - status
      properties:
        label:
          type: string
        role:
          type: string
        model_provider:
          type: string
        provider:
          type: string
        model:
          type: string
        monthly_budget_usd:
          type: number
          format: double
        estimated_spend_usd:
          type: number
          format: double
        remaining_budget_usd:
          type: number
          format: double
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - Active
          - Near budget
          - Budget reached
          - Uncapped
    AgentConfig:
      type: object
      required:
      - agent_name
      - namespace
      - image
      properties:
        agent_name:
          type: string
        namespace:
          type: string
        image:
          type: string
        runtime:
          type: string
        system_prompt:
          type: string
        identity_provider:
          type: string
        llm_configs:
          type: array
          items:
            $ref: '#/components/schemas/AgentConfigLLM'
        model_usage:
          type: array
          items:
            $ref: '#/components/schemas/AgentModelUsage'
        required_tools:
          type: array
          items:
            type: string
        policies:
          type: array
          items:
            type: string
    AgentConfigUpdateRequest:
      type: object
      properties:
        system_prompt:
          type: string
        identity_provider:
          type: string
        llm_configs:
          type: array
          items:
            $ref: '#/components/schemas/AgentConfigLLM'
        required_tools:
          type: array
          items:
            type: string
        policies:
          type: array
          items:
            type: string
    ToolApiKeyConfig:
      type: object
      properties:
        in:
          type: string
        name:
          type: string
        valuePrefix:
          type: string
        secretRef:
          $ref: '#/components/schemas/SecretRef'
    ToolOAuth2Config:
      type: object
      properties:
        authUrl:
          type: string
          format: uri
        tokenUrl:
          type: string
          format: uri
        scopes:
          type: array
          items:
            type: string
        authParams:
          type: object
          additionalProperties:
            type: string
        credentialsSecretRef:
          $ref: '#/components/schemas/SecretRef'
    ToolAuthentication:
      type: object
      properties:
        type:
          type: string
          enum:
          - None
          - APIKey
          - OAuth2
        apiKeyConfig:
          $ref: '#/components/schemas/ToolApiKeyConfig'
        oauth2Config:
          $ref: '#/components/schemas/ToolOAuth2Config'
    ToolConnection:
      type: object
      properties:
        topology:
          type: string
        baseUrl:
          type: string
          format: uri
        port:
          type: integer
        scheme:
          type: string
        authentication:
          $ref: '#/components/schemas/ToolAuthentication'
        tls:
          type: object
          additionalProperties: true
    ToolCapability:
      type: object
      properties:
        name:
          type: string
        method:
          type: string
        path:
          type: string
        description:
          type: string
        riskTags:
          type: array
          items:
            type: string
    ToolGovernance:
      type: object
      additionalProperties: true
    ToolSpec:
      type: object
      properties:
        description:
          type: string
        connection:
          $ref: '#/components/schemas/ToolConnection'
        governance:
          $ref: '#/components/schemas/ToolGovernance'
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/ToolCapability'
        riskTags:
          type: array
          items:
            type: string
    ToolStatus:
      type: object
      properties:
        phase:
          type: string
        last_probe_time:
          type: string
          format: date-time
        probe_latency_ms:
          type: integer
    Tool:
      type: object
      required:
      - name
      - spec
      properties:
        name:
          type: string
        namespace:
          type: string
        spec:
          $ref: '#/components/schemas/ToolSpec'
        status:
          $ref: '#/components/schemas/ToolStatus'
    ToolCredentials:
      type: object
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        api_key:
          type: string
    ToolCreateRequest:
      type: object
      required:
      - name
      - spec
      properties:
        name:
          type: string
        spec:
          $ref: '#/components/schemas/ToolSpec'
        credentials:
          $ref: '#/components/schemas/ToolCredentials'
    ProbeRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
    ProbeResult:
      type: object
      properties:
        reachable:
          type: boolean
        status_code:
          type: integer
        latency_ms:
          type: integer
    ModelProviderAuth:
      type: object
      additionalProperties: true
    ModelProviderRateLimit:
      type: object
      properties:
        requestsPerMinute:
          type: integer
    ModelProviderSpec:
      type: object
      properties:
        provider:
          type: string
        endpoint:
          type: string
          format: uri
        models:
          type: array
          items:
            type: string
        auth:
          $ref: '#/components/schemas/ModelProviderAuth'
        rateLimit:
          $ref: '#/components/schemas/ModelProviderRateLimit'
    ModelProviderStatus:
      type: object
      properties:
        phase:
          type: string
        message:
          type: string
    ModelProvider:
      type: object
      required:
      - name
      - spec
      properties:
        name:
          type: string
        namespace:
          type: string
        spec:
          $ref: '#/components/schemas/ModelProviderSpec'
        status:
          $ref: '#/components/schemas/ModelProviderStatus'
    ModelProviderUpsertRequest:
      type: object
      required:
      - name
      - spec
      properties:
        name:
          type: string
        spec:
          $ref: '#/components/schemas/ModelProviderSpec'
    ModelSpendSummary:
      type: object
      required:
      - total_estimated_spend_usd
      - total_budget_usd
      - remaining_budget_usd
      - budgeted_model_count
      - near_budget_count
      - blocked_count
      - uncapped_spend_usd
      properties:
        total_estimated_spend_usd:
          type: number
          format: double
        total_budget_usd:
          type: number
          format: double
        remaining_budget_usd:
          type: number
          format: double
        budgeted_model_count:
          type: integer
        near_budget_count:
          type: integer
        blocked_count:
          type: integer
        uncapped_spend_usd:
          type: number
          format: double
        period_start:
          type: string
          format: date-time
        period_end:
          type: string
          format: date-time
    ModelSpendItem:
      allOf:
      - $ref: '#/components/schemas/AgentModelUsage'
      - type: object
        required:
        - agent_name
        - agent_namespace
        properties:
          agent_name:
            type: string
          agent_namespace:
            type: string
    ModelSpendResponse:
      type: object
      required:
      - summary
      - warnings
      - top_models
      properties:
        summary:
          $ref: '#/components/schemas/ModelSpendSummary'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ModelSpendItem'
        top_models:
          type: array
          items:
            $ref: '#/components/schemas/ModelSpendItem'
    ChatMessage:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
        content:
          oneOf:
          - type: string
          - type: array
            items:
              type: object
              additionalProperties: true
    ChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
        max_tokens:
          type: integer
        stream:
          type: boolean
        top_p:
          type: number
        frequency_penalty:
          type: number
        presence_penalty:
          type: number
        stop:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
    ChatCompletionChoice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
    ChatCompletionUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/ChatCompletionUsage'
    BuildStatus:
      type: string
      enum:
      - PENDING
      - BUILDING
      - SUCCEEDED
      - FAILED
    Build:
      type: object
      required:
      - id
      - status
      - image
      - created_at
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/BuildStatus'
        image:
          type: string
        error:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    BuildRequest:
      type: object
      required:
      - name
      - files
      properties:
        name:
          type: string
        files:
          type: object
          additionalProperties:
            type: string
        entry_point:
          type: string
        requirements:
          type: string
        framework:
          type: string
