MINE AispmPublicAgents API

openapi: 3.2.0
info:
  title: MineOS Aispm Aispm Public Agents API
  version: v1.0
servers:
- url: https://api.portal.saymine.com/
  description: MineOS EU API Endpoint
- url: https://api.us.portal.saymine.com/
  description: MineOS US API Endpoint
security:
- Bearer: []
tags:
- name: AispmPublicAgents
paths:
  /api/aispm/v1/public/agents:
    get:
      tags:
      - AispmPublicAgents
      summary: 'Lists every AI agent discovered for the authenticated tenant, with rollups derived on read: device

        count, current posture score, current risk score/level, and business-purpose classification (D26).

        Returns an empty array if the tenant has no discovered agents yet — never a 404.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentListItemDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/aispm/v1/public/agents/{id}:
    get:
      tags:
      - AispmPublicAgents
      summary: 'Retrieves full detail for one discovered agent: its tools, skills, every device it was found on

        (each fully expanded), its business-purpose classification, and its current risk/posture scores.'
      parameters:
      - name: id
        in: path
        description: The agent's unique identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDetailDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/aispm/v1/public/agents/{id}/vulnerabilities:
    get:
      tags:
      - AispmPublicAgents
      summary: 'Returns the vulnerabilities found on the agent''s current posture-analysis run, joined to the

        vulnerability catalog. Served separately from M:Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AispmPublicAgentsController.GetAgentSignals(System.Guid,System.Threading.CancellationToken) — the two risk-factor

        collections are never unioned (D35). If the agent has no completed posture run yet, returns an

        empty list with null run/score fields rather than a 404.'
      parameters:
      - name: id
        in: path
        description: The agent's unique identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentVulnerabilitiesDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/aispm/v1/public/agents/{id}/signals:
    get:
      tags:
      - AispmPublicAgents
      summary: 'Returns the governance signals from the agent''s current insights run — the second, separately

        served risk-factor collection (never unioned with vulnerabilities, D35). If the agent has no

        completed insights run yet, returns an empty list with null run/score fields rather than a 404.'
      parameters:
      - name: id
        in: path
        description: The agent's unique identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSignalsDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    AgentSignalDto:
      type: object
      properties:
        signalType:
          type:
          - string
          - 'null'
          description: The kind of governance signal (e.g. data-access pattern, vendor exposure).
        riskLevel:
          type:
          - string
          - 'null'
          description: The signal's risk level.
        scoreContribution:
          type: integer
          description: How much this signal contributes to the agent's overall risk score.
          format: int32
        toolId:
          type:
          - string
          - 'null'
          description: The tool this signal relates to, if applicable.
          format: uuid
        vendorRef:
          type:
          - string
          - 'null'
          description: The vendor this signal relates to, if applicable.
          format: uuid
        explanation:
          type:
          - string
          - 'null'
          description: A human-readable explanation of this signal.
        dataTypes:
          type:
          - array
          - 'null'
          items:
            type: string
          description: The categories of data this signal concerns, if applicable.
        link:
          type:
          - string
          - 'null'
          description: A link to further reading about this signal, if available.
      additionalProperties: false
      description: One governance signal from an insights run.
    AgentVulnerabilityDto:
      type: object
      properties:
        vulnerabilityCode:
          type:
          - string
          - 'null'
          description: The catalog code identifying this vulnerability type.
        category:
          type:
          - string
          - 'null'
          description: The vulnerability's catalog category.
        name:
          type:
          - string
          - 'null'
          description: The vulnerability's catalog name.
        riskLevel:
          type:
          - string
          - 'null'
          description: The vulnerability's risk level.
        confidence:
          type: integer
          description: Detector confidence, 0-100.
          format: int32
        scoreContribution:
          type: integer
          description: How much this finding contributes to the agent's overall posture score.
          format: int32
        codeRef:
          type:
          - string
          - 'null'
          description: A reference to where in the agent's definition this was found, if applicable.
        snippetHash:
          type:
          - string
          - 'null'
          description: 'A hash of the matched snippet — never the raw matched value (P13: evidence is a reference, not the secret).'
        attackSurface:
          type:
          - array
          - 'null'
          items:
            type: string
          description: The attack-surface tags this vulnerability exposes.
        remediation:
          type:
          - string
          - 'null'
          description: Suggested remediation for this finding, if available.
      additionalProperties: false
      description: One vulnerability finding, joined to the vulnerability catalog.
    AgentListItemDto:
      type: object
      properties:
        id:
          type: string
          description: The agent's unique identifier.
          format: uuid
        displayName:
          type:
          - string
          - 'null'
          description: The agent's display name, if known.
        applicationType:
          type:
          - string
          - 'null'
          description: The kind of application this agent runs as (e.g. browser extension, CLI tool, IDE plugin).
        findingType:
          type:
          - string
          - 'null'
          description: How this agent was found (e.g. process scan, browser extension inventory).
        status:
          type:
          - string
          - 'null'
          description: The agent's current lifecycle status.
        llms:
          type:
          - array
          - 'null'
          items:
            type: string
          description: The LLM providers/models this agent is known to call.
        vendorId:
          type:
          - string
          - 'null'
          description: The vendor this agent is attributed to, if resolved.
          format: uuid
        deviceCount:
          type: integer
          description: The number of devices this agent is currently present on (derived, not stored).
          format: int32
        firstSeenAt:
          type:
          - string
          - 'null'
          description: The earliest time this agent was seen on any device.
          format: date-time
        lastSeenAt:
          type:
          - string
          - 'null'
          description: The most recent time this agent was seen on any device.
          format: date-time
        postureScore:
          type:
          - integer
          - 'null'
          description: The agent's current posture score, or null if it has no completed posture run yet.
          format: int32
        riskScore:
          type:
          - integer
          - 'null'
          description: The agent's current risk score, or null if it has no completed insights run yet.
          format: int32
        riskLevel:
          type:
          - string
          - 'null'
          description: The agent's current risk level (derived from Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentListItemDto.RiskScore), or null.
        businessPurpose:
          $ref: '#/components/schemas/AgentBusinessPurposeDto'
      additionalProperties: false
      description: An AI agent discovered for the tenant, with rollups derived on read (D26).
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    AgentDetailDto:
      type: object
      properties:
        id:
          type: string
          description: The agent's unique identifier.
          format: uuid
        displayName:
          type:
          - string
          - 'null'
          description: The agent's display name, if known.
        applicationType:
          type:
          - string
          - 'null'
          description: The kind of application this agent runs as (e.g. browser extension, CLI tool, IDE plugin).
        findingType:
          type:
          - string
          - 'null'
          description: How this agent was found (e.g. process scan, browser extension inventory).
        status:
          type:
          - string
          - 'null'
          description: The agent's current lifecycle status.
        llms:
          type:
          - array
          - 'null'
          items:
            type: string
          description: The LLM providers/models this agent is known to call.
        vendorId:
          type:
          - string
          - 'null'
          description: The vendor this agent is attributed to, if resolved.
          format: uuid
        deviceCount:
          type: integer
          description: The number of devices this agent is currently present on (derived, not stored).
          format: int32
        firstSeenAt:
          type:
          - string
          - 'null'
          description: The earliest time this agent was seen on any device.
          format: date-time
        lastSeenAt:
          type:
          - string
          - 'null'
          description: The most recent time this agent was seen on any device.
          format: date-time
        postureScore:
          type:
          - integer
          - 'null'
          description: The agent's current posture score, or null if it has no completed posture run yet.
          format: int32
        riskScore:
          type:
          - integer
          - 'null'
          description: The agent's current risk score, or null if it has no completed insights run yet.
          format: int32
        riskLevel:
          type:
          - string
          - 'null'
          description: The agent's current risk level (derived from Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentListItemDto.RiskScore), or null.
        businessPurpose:
          $ref: '#/components/schemas/AgentBusinessPurposeDto'
        definitionSummary:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of what this agent's definition does.
        definitionExcerpt:
          type:
          - string
          - 'null'
          description: A redacted excerpt of the agent's raw definition (see the P13 redaction contract).
        builtinCapabilities:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Built-in capability flags this agent's definition declares.
        tools:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AgentToolDto'
          description: The tools this agent is configured with.
        skills:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AgentSkillDto'
          description: The skills this agent is configured with.
        devices:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AgentDeviceDto'
          description: Every device this agent has been found on, each with its finding-specific state.
      additionalProperties: false
      description: 'Full detail for one discovered agent, extending the list-item fields with tools/skills/devices.

        Note: the inherited Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentListItemDto.FirstSeenAt/Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentListItemDto.LastSeenAt

        are not populated here (they''re a list-endpoint rollup only) — per-device timing is available via

        each element of Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentDetailDto.Devices.'
    DeviceFullDto:
      type: object
      properties:
        id:
          type: string
          description: The device's unique identifier.
          format: uuid
        deviceKey:
          type:
          - string
          - 'null'
          description: A stable key identifying this device across scans.
        hardwareUuid:
          type:
          - string
          - 'null'
          description: The device's hardware UUID.
        platform:
          type:
          - string
          - 'null'
          description: The device's platform (e.g. macOS, Windows, Linux).
        hostname:
          type:
          - string
          - 'null'
          description: The device's hostname, if known.
        mdmSource:
          type:
          - string
          - 'null'
          description: The MDM system this device is enrolled in, if any.
        mdmDeviceId:
          type:
          - string
          - 'null'
          description: This device's identifier within its MDM system, if enrolled.
        ownerRawIdentifier:
          type:
          - string
          - 'null'
          description: The raw, unresolved identifier for this device's owner (see the P13 redaction contract).
        ownerEmployeeId:
          type:
          - string
          - 'null'
          description: The resolved employee this device is attributed to, if matched.
          format: uuid
        firstSeenAt:
          type: string
          description: The first time this device was scanned.
          format: date-time
        lastSeenAt:
          type: string
          description: The most recent time this device was scanned.
          format: date-time
        lastScanRunId:
          type:
          - string
          - 'null'
          description: This device's most recent scan run, if any.
          format: uuid
        scannerVersion:
          type:
          - string
          - 'null'
          description: The scanner version used on this device's last scan run.
        attributes:
          $ref: '#/components/schemas/DeviceAttributesDto'
      additionalProperties: false
      description: Every Device column ("show everything") plus the scanner version from its last scan run.
    AgentBusinessPurposeDto:
      type: object
      properties:
        purpose:
          type:
          - string
          - 'null'
          description: The classified business purpose (e.g. "customer support automation").
        confidence:
          type: integer
          description: Classifier confidence, 0-100.
          format: int32
        explanation:
          type:
          - string
          - 'null'
          description: A short explanation of why this purpose was assigned.
        insightsRunId:
          type:
          - string
          - 'null'
          description: The insights run that produced this classification, if any.
          format: uuid
      additionalProperties: false
      description: 'Business-purpose classification as a full object (source: AgentBusinessPurpose, 1:1 with Agent).'
    AgentSignalsDto:
      type: object
      properties:
        insightsRunId:
          type:
          - string
          - 'null'
          description: The insights run these signals came from, or null if none has completed yet.
          format: uuid
        riskScore:
          type:
          - integer
          - 'null'
          description: The risk score from that run, or null if none has completed yet.
          format: int32
        riskLevel:
          type:
          - string
          - 'null'
          description: The risk level from that run, or null.
        signals:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AgentSignalDto'
          description: The governance signals found in that run.
      additionalProperties: false
      description: An agent's governance signals from its current insights run.
    AgentToolDto:
      type: object
      properties:
        toolKey:
          type:
          - string
          - 'null'
          description: The tool's stable key (identity within the tool catalog).
        toolKind:
          type:
          - string
          - 'null'
          description: The tool's kind (e.g. built-in, MCP server, custom function).
        displayName:
          type:
          - string
          - 'null'
          description: The tool's display name, if known.
        resolutionState:
          type:
          - string
          - 'null'
          description: Whether this tool link resolved to a known catalog entry.
        permissions:
          type:
          - string
          - 'null'
          description: The permissions declared for this tool, if any.
        effectivePermissions:
          type:
          - string
          - 'null'
          description: The permissions this tool actually has effective access to, if computed.
      additionalProperties: false
      description: A tool this agent is configured to use.
    DeviceAttributesDto:
      type: object
      properties:
        macAddresses:
          type:
          - array
          - 'null'
          items:
            type: string
          description: The device's known MAC addresses.
        osVersion:
          type:
          - string
          - 'null'
          description: The device's operating system version.
        hardwareModel:
          type:
          - string
          - 'null'
          description: The device's hardware model.
        arch:
          type:
          - string
          - 'null'
          description: The device's CPU architecture.
      additionalProperties: false
      description: Additional device attributes collected by the scanner.
    AgentVulnerabilitiesDto:
      type: object
      properties:
        postureAnalysisRunId:
          type:
          - string
          - 'null'
          description: The posture-analysis run these vulnerabilities came from, or null if none has completed yet.
          format: uuid
        postureScore:
          type:
          - integer
          - 'null'
          description: The posture score from that run, or null if none has completed yet.
          format: int32
        vulnerabilities:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AgentVulnerabilityDto'
          description: The vulnerabilities found in that run, joined to the vulnerability catalog.
      additionalProperties: false
      description: An agent's vulnerabilities from its current posture-analysis run.
    AgentSkillDto:
      type: object
      properties:
        skillKey:
          type:
          - string
          - 'null'
          description: The skill's stable key (identity within the skill catalog).
        displayName:
          type:
          - string
          - 'null'
          description: The skill's display name, if known.
        version:
          type:
          - string
          - 'null'
          description: The skill's version, if known.
      additionalProperties: false
      description: A skill this agent is configured to use.
    AgentDeviceDto:
      type: object
      properties:
        state:
          type:
          - string
          - 'null'
          description: Whether the agent is currently present on this device, or historical.
        firstSeenAt:
          type: string
          description: The first time this agent was seen on this device.
          format: date-time
        lastSeenAt:
          type: string
          description: The most recent time this agent was seen on this device.
          format: date-time
        device:
          $ref: '#/components/schemas/DeviceFullDto'
      additionalProperties: false
      description: 'One agent-on-device occurrence: the finding-specific fields plus the full device record.'
  securitySchemes:
    Bearer:
      type: apiKey
      description: "Authorization header using the Bearer scheme. \n\nEnter 'Bearer' [space] and then your API Key in the text input below.\n\nExample: 'Bearer 12345abcdef'"
      name: Authorization
      in: header