MINE AispmPublicAgents API

openapi: 3.0.1
info:
  title: MineOS Aispm AispmPublicAgents 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\r\ncount, current posture score, current risk score/level, and business-purpose classification (D26).\r\nReturns 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\r\n(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\r\nvulnerability catalog. Served separately from M:Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AispmPublicAgentsController.GetAgentSignals(System.Guid,System.Threading.CancellationToken) — the two risk-factor\r\ncollections are never unioned (D35). If the agent has no completed posture run yet, returns an\r\nempty 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\r\nserved risk-factor collection (never unioned with vulnerabilities, D35). If the agent has no\r\ncompleted 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:
    AgentDeviceDto:
      type: object
      properties:
        state:
          type: string
          description: Whether the agent is currently present on this device, or historical.
          nullable: true
        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.'
    AgentDetailDto:
      type: object
      properties:
        id:
          type: string
          description: The agent's unique identifier.
          format: uuid
        displayName:
          type: string
          description: The agent's display name, if known.
          nullable: true
        applicationType:
          type: string
          description: The kind of application this agent runs as (e.g. browser extension, CLI tool, IDE plugin).
          nullable: true
        findingType:
          type: string
          description: How this agent was found (e.g. process scan, browser extension inventory).
          nullable: true
        status:
          type: string
          description: The agent's current lifecycle status.
          nullable: true
        llms:
          type: array
          items:
            type: string
          description: The LLM providers/models this agent is known to call.
          nullable: true
        vendorId:
          type: string
          description: The vendor this agent is attributed to, if resolved.
          format: uuid
          nullable: true
        deviceCount:
          type: integer
          description: The number of devices this agent is currently present on (derived, not stored).
          format: int32
        firstSeenAt:
          type: string
          description: The earliest time this agent was seen on any device.
          format: date-time
          nullable: true
        lastSeenAt:
          type: string
          description: The most recent time this agent was seen on any device.
          format: date-time
          nullable: true
        postureScore:
          type: integer
          description: The agent's current posture score, or null if it has no completed posture run yet.
          format: int32
          nullable: true
        riskScore:
          type: integer
          description: The agent's current risk score, or null if it has no completed insights run yet.
          format: int32
          nullable: true
        riskLevel:
          type: string
          description: The agent's current risk level (derived from Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentListItemDto.RiskScore), or null.
          nullable: true
        businessPurpose:
          $ref: '#/components/schemas/AgentBusinessPurposeDto'
        definitionSummary:
          type: string
          description: A short, human-readable summary of what this agent's definition does.
          nullable: true
        definitionExcerpt:
          type: string
          description: A redacted excerpt of the agent's raw definition (see the P13 redaction contract).
          nullable: true
        builtinCapabilities:
          type: array
          items:
            type: string
          description: Built-in capability flags this agent's definition declares.
          nullable: true
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AgentToolDto'
          description: The tools this agent is configured with.
          nullable: true
        skills:
          type: array
          items:
            $ref: '#/components/schemas/AgentSkillDto'
          description: The skills this agent is configured with.
          nullable: true
        devices:
          type: array
          items:
            $ref: '#/components/schemas/AgentDeviceDto'
          description: Every device this agent has been found on, each with its finding-specific state.
          nullable: true
      additionalProperties: false
      description: "Full detail for one discovered agent, extending the list-item fields with tools/skills/devices.\r\nNote: the inherited Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentListItemDto.FirstSeenAt/Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentListItemDto.LastSeenAt\r\nare not populated here (they're a list-endpoint rollup only) — per-device timing is available via\r\neach element of Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentDetailDto.Devices."
    AgentVulnerabilitiesDto:
      type: object
      properties:
        postureAnalysisRunId:
          type: string
          description: The posture-analysis run these vulnerabilities came from, or null if none has completed yet.
          format: uuid
          nullable: true
        postureScore:
          type: integer
          description: The posture score from that run, or null if none has completed yet.
          format: int32
          nullable: true
        vulnerabilities:
          type: array
          items:
            $ref: '#/components/schemas/AgentVulnerabilityDto'
          description: The vulnerabilities found in that run, joined to the vulnerability catalog.
          nullable: true
      additionalProperties: false
      description: An agent's vulnerabilities from its current posture-analysis run.
    AgentSkillDto:
      type: object
      properties:
        skillKey:
          type: string
          description: The skill's stable key (identity within the skill catalog).
          nullable: true
        displayName:
          type: string
          description: The skill's display name, if known.
          nullable: true
        version:
          type: string
          description: The skill's version, if known.
          nullable: true
      additionalProperties: false
      description: A skill this agent is configured to use.
    DeviceAttributesDto:
      type: object
      properties:
        macAddresses:
          type: array
          items:
            type: string
          description: The device's known MAC addresses.
          nullable: true
        osVersion:
          type: string
          description: The device's operating system version.
          nullable: true
        hardwareModel:
          type: string
          description: The device's hardware model.
          nullable: true
        arch:
          type: string
          description: The device's CPU architecture.
          nullable: true
      additionalProperties: false
      description: Additional device attributes collected by the scanner.
    AgentToolDto:
      type: object
      properties:
        toolKey:
          type: string
          description: The tool's stable key (identity within the tool catalog).
          nullable: true
        toolKind:
          type: string
          description: The tool's kind (e.g. built-in, MCP server, custom function).
          nullable: true
        displayName:
          type: string
          description: The tool's display name, if known.
          nullable: true
        resolutionState:
          type: string
          description: Whether this tool link resolved to a known catalog entry.
          nullable: true
        permissions:
          type: string
          description: The permissions declared for this tool, if any.
          nullable: true
        effectivePermissions:
          type: string
          description: The permissions this tool actually has effective access to, if computed.
          nullable: true
      additionalProperties: false
      description: A tool this agent is configured to use.
    AgentVulnerabilityDto:
      type: object
      properties:
        vulnerabilityCode:
          type: string
          description: The catalog code identifying this vulnerability type.
          nullable: true
        category:
          type: string
          description: The vulnerability's catalog category.
          nullable: true
        name:
          type: string
          description: The vulnerability's catalog name.
          nullable: true
        riskLevel:
          type: string
          description: The vulnerability's risk level.
          nullable: true
        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
          description: A reference to where in the agent's definition this was found, if applicable.
          nullable: true
        snippetHash:
          type: string
          description: 'A hash of the matched snippet — never the raw matched value (P13: evidence is a reference, not the secret).'
          nullable: true
        attackSurface:
          type: array
          items:
            type: string
          description: The attack-surface tags this vulnerability exposes.
          nullable: true
        remediation:
          type: string
          description: Suggested remediation for this finding, if available.
          nullable: true
      additionalProperties: false
      description: One vulnerability finding, joined to the vulnerability catalog.
    AgentBusinessPurposeDto:
      type: object
      properties:
        purpose:
          type: string
          description: The classified business purpose (e.g. "customer support automation").
          nullable: true
        confidence:
          type: integer
          description: Classifier confidence, 0-100.
          format: int32
        explanation:
          type: string
          description: A short explanation of why this purpose was assigned.
          nullable: true
        insightsRunId:
          type: string
          description: The insights run that produced this classification, if any.
          format: uuid
          nullable: true
      additionalProperties: false
      description: 'Business-purpose classification as a full object (source: AgentBusinessPurpose, 1:1 with Agent).'
    DeviceFullDto:
      type: object
      properties:
        id:
          type: string
          description: The device's unique identifier.
          format: uuid
        deviceKey:
          type: string
          description: A stable key identifying this device across scans.
          nullable: true
        hardwareUuid:
          type: string
          description: The device's hardware UUID.
          nullable: true
        platform:
          type: string
          description: The device's platform (e.g. macOS, Windows, Linux).
          nullable: true
        hostname:
          type: string
          description: The device's hostname, if known.
          nullable: true
        mdmSource:
          type: string
          description: The MDM system this device is enrolled in, if any.
          nullable: true
        mdmDeviceId:
          type: string
          description: This device's identifier within its MDM system, if enrolled.
          nullable: true
        ownerRawIdentifier:
          type: string
          description: The raw, unresolved identifier for this device's owner (see the P13 redaction contract).
          nullable: true
        ownerEmployeeId:
          type: string
          description: The resolved employee this device is attributed to, if matched.
          format: uuid
          nullable: true
        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
          description: This device's most recent scan run, if any.
          format: uuid
          nullable: true
        scannerVersion:
          type: string
          description: The scanner version used on this device's last scan run.
          nullable: true
        attributes:
          $ref: '#/components/schemas/DeviceAttributesDto'
      additionalProperties: false
      description: Every Device column ("show everything") plus the scanner version from its last scan run.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    AgentListItemDto:
      type: object
      properties:
        id:
          type: string
          description: The agent's unique identifier.
          format: uuid
        displayName:
          type: string
          description: The agent's display name, if known.
          nullable: true
        applicationType:
          type: string
          description: The kind of application this agent runs as (e.g. browser extension, CLI tool, IDE plugin).
          nullable: true
        findingType:
          type: string
          description: How this agent was found (e.g. process scan, browser extension inventory).
          nullable: true
        status:
          type: string
          description: The agent's current lifecycle status.
          nullable: true
        llms:
          type: array
          items:
            type: string
          description: The LLM providers/models this agent is known to call.
          nullable: true
        vendorId:
          type: string
          description: The vendor this agent is attributed to, if resolved.
          format: uuid
          nullable: true
        deviceCount:
          type: integer
          description: The number of devices this agent is currently present on (derived, not stored).
          format: int32
        firstSeenAt:
          type: string
          description: The earliest time this agent was seen on any device.
          format: date-time
          nullable: true
        lastSeenAt:
          type: string
          description: The most recent time this agent was seen on any device.
          format: date-time
          nullable: true
        postureScore:
          type: integer
          description: The agent's current posture score, or null if it has no completed posture run yet.
          format: int32
          nullable: true
        riskScore:
          type: integer
          description: The agent's current risk score, or null if it has no completed insights run yet.
          format: int32
          nullable: true
        riskLevel:
          type: string
          description: The agent's current risk level (derived from Mine.Portal.Module.AispmAgentsDemo.Api.PublicApi.AgentListItemDto.RiskScore), or null.
          nullable: true
        businessPurpose:
          $ref: '#/components/schemas/AgentBusinessPurposeDto'
      additionalProperties: false
      description: An AI agent discovered for the tenant, with rollups derived on read (D26).
    AgentSignalsDto:
      type: object
      properties:
        insightsRunId:
          type: string
          description: The insights run these signals came from, or null if none has completed yet.
          format: uuid
          nullable: true
        riskScore:
          type: integer
          description: The risk score from that run, or null if none has completed yet.
          format: int32
          nullable: true
        riskLevel:
          type: string
          description: The risk level from that run, or null.
          nullable: true
        signals:
          type: array
          items:
            $ref: '#/components/schemas/AgentSignalDto'
          description: The governance signals found in that run.
          nullable: true
      additionalProperties: false
      description: An agent's governance signals from its current insights run.
    AgentSignalDto:
      type: object
      properties:
        signalType:
          type: string
          description: The kind of governance signal (e.g. data-access pattern, vendor exposure).
          nullable: true
        riskLevel:
          type: string
          description: The signal's risk level.
          nullable: true
        scoreContribution:
          type: integer
          description: How much this signal contributes to the agent's overall risk score.
          format: int32
        toolId:
          type: string
          description: The tool this signal relates to, if applicable.
          format: uuid
          nullable: true
        vendorRef:
          type: string
          description: The vendor this signal relates to, if applicable.
          format: uuid
          nullable: true
        explanation:
          type: string
          description: A human-readable explanation of this signal.
          nullable: true
        dataTypes:
          type: array
          items:
            type: string
          description: The categories of data this signal concerns, if applicable.
          nullable: true
        link:
          type: string
          description: A link to further reading about this signal, if available.
          nullable: true
      additionalProperties: false
      description: One governance signal from an insights run.
  securitySchemes:
    Bearer:
      type: apiKey
      description: "Authorization header using the Bearer scheme. \r\n\r\nEnter 'Bearer' [space] and then your API Key in the text input below.\r\n\r\nExample: 'Bearer 12345abcdef'"
      name: Authorization
      in: header