> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get the AI risk findings
> Return the AI risk findings, worst severity first, one page as JSON (`data`, `pagination`): each with its `findingKey`, rule code, `severity` and `severityLabel`, a `title` and `description` in words, the device and its owner, and what it is on (`subjectName`, `toolKey`). Filter with `severity` (a list, e.g. critical and high), `rule`, `kind` (a tool kind or `instruction_file`), `deviceId` and `toolKey`. These are the risks of AI tools only: MDM compliance alerts are `getComplianceAlerts`, CVEs `getVulnerabilities`. AI tools are what Primo finds on Macs (assistant apps, coding agents, IDE plugins, browser extensions, MCP servers, AI connections, agent instruction files), as of the last report (`lastSyncedAt` of `getAiToolsOverview`, every 5 minutes), with Primo's severities, less the findings the company's AI tools settings ignore. They are not the software catalog (`getSoftwares`, `getDeviceSoftware`), the company's own AI agents (`listAgents`) nor AI credits (`getAiUsage`). A company without AI tools monitoring gets a 403, final.
Key: ReadScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json get /ai-tools/findings
openapi: 3.1.1
info:
title: Public API - BETA
description: Read docs on https://docs.getprimo.com/
version: '1.0'
contact: {}
servers:
- url: https://api.getprimo.com
security:
- apikey: []
tags: []
paths:
/ai-tools/findings:
get:
tags:
- AiTools
summary: Get the AI risk findings
description: >-
Return the AI risk findings, worst severity first, one page as JSON
(`data`, `pagination`): each with its `findingKey`, rule code,
`severity` and `severityLabel`, a `title` and `description` in words,
the device and its owner, and what it is on (`subjectName`, `toolKey`).
Filter with `severity` (a list, e.g. critical and high), `rule`, `kind`
(a tool kind or `instruction_file`), `deviceId` and `toolKey`. These are
the risks of AI tools only: MDM compliance alerts are
`getComplianceAlerts`, CVEs `getVulnerabilities`. AI tools are what
Primo finds on Macs (assistant apps, coding agents, IDE plugins, browser
extensions, MCP servers, AI connections, agent instruction files), as of
the last report (`lastSyncedAt` of `getAiToolsOverview`, every 5
minutes), with Primo's severities, less the findings the company's AI
tools settings ignore. They are not the software catalog
(`getSoftwares`, `getDeviceSoftware`), the company's own AI agents
(`listAgents`) nor AI credits (`getAiUsage`). A company without AI tools
monitoring gets a 403, final.
operationId: getAiFindings
parameters:
- name: toolKey
required: false
in: query
description: Keep the findings of one tool
schema:
type: string
- name: deviceId
required: false
in: query
description: Keep the findings of one device
schema:
type: string
- name: kind
required: false
in: query
description: Kind of the tool the finding is on, or `instruction_file`
schema:
enum:
- assistant_app
- coding_agent
- ide_plugin
- browser_extension
- mcp_server
- instruction_file
type: string
- name: rule
required: false
in: query
description: A rule's code, e.g. `plaintext_secret`
schema:
type: string
- name: severity
required: false
in: query
description: >-
Keep the findings of these severities (repeat the param or comma
separate)
schema:
type: array
items:
type: string
enum:
- critical
- high
- medium
- low
- name: page
required: false
in: query
description: Page number
schema:
type: number
- name: perPage
required: false
in: query
description: Number of items per page (max 100)
schema:
type: number
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetAiFindingsResponse_Output'
components:
schemas:
GetAiFindingsResponse_Output:
type: object
properties:
data:
type: array
items:
type: object
properties:
rule:
description: Primo's code of the risk, e.g. `plaintext_secret`
type: string
severity:
description: Primo's severity of the rule
type: string
enum:
- critical
- high
- medium
- low
severityLabel:
description: The severity in words, e.g. `Critical`
type: string
title:
description: >-
What the rule means in a few words; the code itself for a rule
Primo has not rated yet
type: string
description:
description: One line on what the rule detects
anyOf:
- type: string
- type: 'null'
findingKey:
description: Stable identifier of the finding
type: string
reportedAt:
description: When the device reported the item to Primo (ISO 8601)
type: string
subjectType:
type: string
enum:
- tool
- instruction_file
subjectName:
description: Name of the tool, or file name of the instruction file
type: string
toolKey:
description: The tool the finding is on; null for an instruction file
anyOf:
- type: string
- type: 'null'
toolKind:
anyOf:
- description: >-
assistant_app (Claude, ChatGPT desktop), coding_agent
(Claude Code, Codex), ide_plugin, browser_extension or
mcp_server
type: string
enum:
- assistant_app
- coding_agent
- ide_plugin
- browser_extension
- mcp_server
- type: 'null'
deviceId:
description: Primo device id, to pass to `getAiToolsDevice` or `getDevice`
type: string
deviceName:
anyOf:
- type: string
- type: 'null'
serialNumber:
anyOf:
- type: string
- type: 'null'
platform:
anyOf:
- type: string
enum:
- ANDROID
- IOS
- IPADOS
- MACOS
- WINDOWS
- LINUX
- CHROME_OS
- UNKNOWN
- type: 'null'
ownerId:
description: Employee id of the device owner
anyOf:
- type: string
- type: 'null'
ownerName:
anyOf:
- type: string
- type: 'null'
required:
- rule
- severity
- severityLabel
- title
- description
- findingKey
- reportedAt
- subjectType
- subjectName
- toolKey
- toolKind
- deviceId
- deviceName
- serialNumber
- platform
- ownerId
- ownerName
additionalProperties: false
pagination:
type: object
properties:
totalElements:
type: integer
minimum: 0
maximum: 9007199254740991
totalPages:
type: integer
minimum: 0
maximum: 9007199254740991
page:
type: integer
minimum: 1
maximum: 9007199254740991
perPage:
type: integer
minimum: 1
maximum: 100
required:
- totalElements
- totalPages
- page
- perPage
additionalProperties: false
required:
- data
- pagination
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.