> ## 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 one device's AI inventory
> Return one device's AI inventory (`deviceId` from `getAiToolsDevices` or `getAiFindings`): its tools with versions and paths (the home folder written `~`), each MCP server (transport, endpoint host, executable, package, the names of its environment variables, never their values), browser extensions, the connections to AI services over the last 24 hours, the agent instruction files, and its findings with their titles. A 404 means Primo has no AI tools report for the device. 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/devices/{deviceId}
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/devices/{deviceId}:
get:
tags:
- AiTools
summary: Get one device's AI inventory
description: >-
Return one device's AI inventory (`deviceId` from `getAiToolsDevices` or
`getAiFindings`): its tools with versions and paths (the home folder
written `~`), each MCP server (transport, endpoint host, executable,
package, the names of its environment variables, never their values),
browser extensions, the connections to AI services over the last 24
hours, the agent instruction files, and its findings with their titles.
A 404 means Primo has no AI tools report for the device. 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: getAiToolsDevice
parameters:
- name: deviceId
required: true
in: path
schema:
type: string
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetAiToolsDeviceResponse_Output'
components:
schemas:
GetAiToolsDeviceResponse_Output:
type: object
properties:
device:
type: object
properties:
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'
toolsReportedAt:
description: When the device last reported its tools to Primo (ISO 8601)
anyOf:
- type: string
- type: 'null'
toolCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
runningToolCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
mcpServerCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
remoteConnectionCount:
description: Connections to AI services outside the device, last 24 hours
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
instructionFileCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
findingCounts:
type: object
properties:
critical:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
high:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
medium:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
low:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- critical
- high
- medium
- low
additionalProperties: false
worstSeverity:
anyOf:
- type: string
enum:
- critical
- high
- medium
- low
- type: 'null'
worstSeverityLabel:
anyOf:
- type: string
- type: 'null'
required:
- deviceId
- deviceName
- serialNumber
- platform
- ownerId
- ownerName
- toolsReportedAt
- toolCount
- runningToolCount
- mcpServerCount
- remoteConnectionCount
- instructionFileCount
- findingCounts
- worstSeverity
- worstSeverityLabel
additionalProperties: false
tools:
description: null when the device never reported it to Primo
anyOf:
- type: object
properties:
reportedAt:
description: >-
When the device last reported the section to Primo (ISO
8601)
type: string
items:
type: array
items:
type: object
properties:
toolKey:
type: string
kind:
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
name:
type: string
vendor:
anyOf:
- type: string
- type: 'null'
identifier:
type: string
version:
anyOf:
- type: string
- type: 'null'
running:
type: boolean
source:
anyOf:
- type: string
- type: 'null'
path:
anyOf:
- type: string
- type: 'null'
riskFlags:
description: >-
Codes of the rules the item raises; their titles are
in `findings`
type: array
items:
type: string
mcpServer:
anyOf:
- type: object
properties:
transport:
anyOf:
- type: string
- type: 'null'
endpoint:
description: Scheme and host only
anyOf:
- type: string
- type: 'null'
command:
description: >-
The executable that starts the server, never
its arguments
anyOf:
- type: string
- type: 'null'
package:
anyOf:
- type: string
- type: 'null'
envKeys:
description: >-
Names of the environment variables set, never
their values
type: array
items:
type: string
scope:
anyOf:
- type: string
- type: 'null'
required:
- transport
- endpoint
- command
- package
- envKeys
- scope
additionalProperties: false
- type: 'null'
browserExtension:
anyOf:
- type: object
properties:
browser:
anyOf:
- type: string
- type: 'null'
profile:
anyOf:
- type: string
- type: 'null'
fromWebstore:
anyOf:
- type: boolean
- type: 'null'
required:
- browser
- profile
- fromWebstore
additionalProperties: false
- type: 'null'
required:
- toolKey
- kind
- name
- vendor
- identifier
- version
- running
- source
- path
- riskFlags
- mcpServer
- browserExtension
additionalProperties: false
required:
- reportedAt
- items
additionalProperties: false
- type: 'null'
connections:
description: null when the device never reported it to Primo
anyOf:
- type: object
properties:
reportedAt:
description: >-
When the device last reported the section to Primo (ISO
8601)
type: string
items:
type: array
items:
type: object
properties:
process:
type: string
service:
anyOf:
- type: string
- type: 'null'
category:
anyOf:
- type: string
- type: 'null'
endpoint:
anyOf:
- type: string
- type: 'null'
location:
description: '`remote` for a host outside the device'
anyOf:
- type: string
- type: 'null'
path:
anyOf:
- type: string
- type: 'null'
firstSeenAt:
type: string
lastSeenAt:
type: string
required:
- process
- service
- category
- endpoint
- location
- path
- firstSeenAt
- lastSeenAt
additionalProperties: false
required:
- reportedAt
- items
additionalProperties: false
- type: 'null'
instructionFiles:
description: null when the device never reported it to Primo
anyOf:
- type: object
properties:
reportedAt:
description: >-
When the device last reported the section to Primo (ISO
8601)
type: string
items:
type: array
items:
type: object
properties:
tool:
type: string
name:
type: string
path:
type: string
sha256:
anyOf:
- type: string
- type: 'null'
scope:
anyOf:
- type: string
- type: 'null'
markers:
type: array
items:
type: string
riskFlags:
description: >-
Codes of the rules the item raises; their titles are
in `findings`
type: array
items:
type: string
required:
- tool
- name
- path
- sha256
- scope
- markers
- riskFlags
additionalProperties: false
required:
- reportedAt
- items
additionalProperties: false
- type: 'null'
findings:
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'
path:
description: Path of the configuration or file, the home folder written `~`
anyOf:
- type: string
- type: 'null'
required:
- rule
- severity
- severityLabel
- title
- description
- findingKey
- reportedAt
- subjectType
- subjectName
- toolKey
- toolKind
- path
additionalProperties: false
required:
- device
- tools
- connections
- instructionFiles
- findings
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.