> ## 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 AI tool and the devices it is on
> Return one AI tool (`toolKey` from `getAiTools`) and every device it is on: the device and its owner, the versions, whether it runs, where it is configured (`sources`), its MCP endpoints (scheme and host only) and its findings with their titles and paths (the home folder written `~`). A 404 means no device reports the tool. 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/tools/{toolKey}
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/tools/{toolKey}:
get:
tags:
- AiTools
summary: Get one AI tool and the devices it is on
description: >-
Return one AI tool (`toolKey` from `getAiTools`) and every device it is
on: the device and its owner, the versions, whether it runs, where it is
configured (`sources`), its MCP endpoints (scheme and host only) and its
findings with their titles and paths (the home folder written `~`). A
404 means no device reports the tool. 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: getAiTool
parameters:
- name: toolKey
required: true
in: path
schema:
type: string
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetAiToolResponse_Output'
components:
schemas:
GetAiToolResponse_Output:
type: object
properties:
tool:
type: object
properties:
toolKey:
description: >-
Identifier of the tool, to pass to `getAiTool` or
`getAiFindings`
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'
deviceCount:
description: Devices the tool was found on
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
runningDeviceCount:
description: Devices the tool was running on at the last report
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
topVersion:
description: The version found on the most devices
anyOf:
- type: string
- type: 'null'
versions:
type: array
items:
type: object
properties:
version:
type: string
deviceCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- version
- deviceCount
additionalProperties: false
worstSeverity:
description: Worst severity of its findings; null without finding
anyOf:
- type: string
enum:
- critical
- high
- medium
- low
- type: 'null'
worstSeverityLabel:
anyOf:
- type: string
- type: 'null'
findingCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- toolKey
- kind
- name
- vendor
- deviceCount
- runningDeviceCount
- topVersion
- versions
- worstSeverity
- worstSeverityLabel
- findingCount
additionalProperties: false
devices:
type: array
items:
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'
reportedAt:
type: string
versions:
type: array
items:
type: string
running:
type: boolean
sources:
description: Where the tool is configured or installed from
type: array
items:
type: string
endpoints:
description: MCP endpoints, scheme and host only
type: array
items:
type: string
worstSeverity:
anyOf:
- type: string
enum:
- critical
- high
- medium
- low
- type: 'null'
worstSeverityLabel:
anyOf:
- type: string
- 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:
- deviceId
- deviceName
- serialNumber
- platform
- ownerId
- ownerName
- reportedAt
- versions
- running
- sources
- endpoints
- worstSeverity
- worstSeverityLabel
- findings
additionalProperties: false
required:
- tool
- devices
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.