API reference Resources
Inventory
AI tools and artifacts found on the fleet.
11 operations
AI tool settings
This workspace's AI tool settings, or the defaults when it has never set any.
An empty corporate_domains is the default and is a working configuration, not an error state: with nothing configured, a built-in list of consumer providers applies.
Response200
The workspace's corporate email domains
Lower-cased bare domains: northwind.com, never @northwind.com.
In the order they were entered. Empty is valid and is the default: with nothing configured, a built-in list of consumer providers applies.
Errors
- 401
No valid session
- 403
Caller lacks machines:read in this workspace
- 404
No such workspace, or the caller is not a member
Replace this workspace's corporate domain list
Replace this workspace's corporate domain list.
The list you send replaces the whole list; there is no add or remove.
Every change is recorded in the audit log, with the list as stored, which is the list that will actually be used rather than the one that was sent.
Request bodyPutAiToolSettingsRequest
Response200
The stored settings, after normalisation
Lower-cased bare domains: northwind.com, never @northwind.com.
In the order they were entered. Empty is valid and is the default: with nothing configured, a built-in list of consumer providers applies.
Errors
- 400
Malformed body, or an entry that is not a bare domain — the message names it
- 401
No valid session
- 403
Caller lacks fleet:manage in this workspace
- 404
No such workspace, or the caller is not a member
Unlock a session lock
The lock stays in place until the machine's next check-in carries the unlock. Calling this again gives the same answer. Recorded in the audit log.
Path parameters
Response200
The lock, now unlock_pending.
What matched, in a few words.
The words the person sees on every refused call.
agent (a Hook policy) or server (a Session-log policy).
The machine the unlock reaches at its next check-in, by hostname.
Errors
- 403
Unlocking requires policies:write in this workspace
- 404
No live lock with this id in this workspace
One AI tool on one machine
The tool's header, counts, coverage and the policies that govern it. artifact is the AI tool's artifact id; 404 when this workspace holds no such AI tool.
Path parameters
Response200
The single-record artifact view, tool_settings filled.
Whether the server holds the artifact's whole body, matched to the hash this row carries.
Use this, not preview_truncated, to tell whether the whole artifact was scanned: a long artifact can have a truncated preview and still a full scan.
Unresolved issues about this artifact, and the worst of them.
0 with a null severity is a real answer: nothing has checked this artifact yet, which is not the same as it being clean.
The provided AI-tool checks (AI tool safety, MCP server safety), each policy id with its key. An issue whose source_id is one of these policy ids is a setting issue from that check.
approval_bypass, shell_auto_approved, …
Counts for the header, tabs and tiles. A count that could not be read is omitted, never `0`.
Whether the agent can fix this tool's settings by writing its enforced settings file.
The agent's last beat reported it holding for this tool.
enforce or monitor.
Whether this tool can be locked: its hooks can refuse.
active, suspended, archived, uninstalled or deleted.
The agent build the machine last reported; null when unknown.
The machine's last check-in, RFC 3339; null when it has never checked in or the read failed. The Sessions tab's nothing received yet checklist names it.
At most 200, newest first.
auto_approved, asked or denied.
The session it is attributed to, or null: Saved outside a known session.
Whether the agent can read this tool's sessions. When false, there are no sessions to list.
The tool's last seven days of sessions. Absent when they could not be read, never reported as zeros.
Seven UTC days ending today, oldest first; a day with no session is 0.
Distinct named projects across those sessions.
Prompts across those sessions.
The sum of days.
The newest last_at of any session ever received; null when none ever was.
One live session lock, and the decision that locked it.
What matched, in a few words.
The words the person sees on every refused call.
agent (a Hook policy) or server (a Session-log policy).
Errors
- 404
No such AI tool in this workspace
List an AI tool's sessions
One tool's sessions on one machine, newest first, paged by cursor.
Path parameters
Query parameters
1d, 7d or 30d (the default).
An oversight word: the session ran in it at some point.
The next of the previous page.
At most 50.
Response200
Errors
- 400
A malformed filter
- 404
No such AI tool in this workspace
One session of one tool
Path parameters
Response200
Derived from mcp__<server>__<tool> names.
kept or not_kept.
What the Interactions list shows for that interaction: null when the logging mode removed it.
One live session lock, and the decision that locked it.
What matched, in a few words.
The words the person sees on every refused call.
agent (a Hook policy) or server (a Session-log policy).
The session's last permission mode, as an oversight word.
The caller may not read interaction content, so no first prompt is shown.
Errors
- 404
No such session of this tool
The AI Artifacts index
Query parameters
The filter expression, e.g. all;category~in~agent_skill;severity~nin~low.
A malformed segment is dropped; a field this list does not have is a 400 naming it.
Free text over name and location. ANDs with the expression whichever way its conditions are joined.
Where the previous page stopped. Opaque; an unreadable one starts over.
Rows wanted, at most 200; a larger value returns 200.
Fold the matched set instead of paging it.
catalogued_identity, catalogued, machine, owner or category. The rollup covers everything the filter matched, not the page — the deleted AI Components page answered how widely is this in use, and an answer folded from fifty rows would be an answer about fifty rows.
An unknown value is a 400 naming the five, for the reason an unknown filter field is: a silently ignored group returns a page of rows to a caller that asked for groups.
Response200
Whether the server holds the artifact's whole body, matched to the hash this row carries.
Use this, not preview_truncated, to tell whether the whole artifact was scanned: a long artifact can have a truncated preview and still a full scan.
Unresolved issues about this artifact, and the worst of them.
0 with a null severity is a real answer: nothing has checked this artifact yet, which is not the same as it being clean.
Everything the filter matched across every page, not just the artifacts on this page.
With group, the number of groups the match folds into, across every page — the count the grouped list is paged against.
Present only when group was asked for, and then artifacts is empty. A page of groups (limit, default 50), continued with next_cursor.
One response type for both shapes, because they are one question asked at two resolutions and a second endpoint would be a second place to add a filter field. Worst first, then largest.
Distinct machines. One component on five machines is the reach an operator is asking about.
One part per field in ?group=, in the order given, each null where the artifact has no value for that field.
One end of a parent/child link. The check summary (catalogued, advisory_severity, flags) is that of the artifact this entry names, read from its stored check.
The value grouped on — the first field's part. null is a real group: unowned, no machine, or nothing catalogued.
Pass back as cursor for the next page. null means this was the last.
One artifact, for the drawer
Path parameters
Response200
Whether the server holds the artifact's whole body, matched to the hash this row carries.
Use this, not preview_truncated, to tell whether the whole artifact was scanned: a long artifact can have a truncated preview and still a full scan.
The parents that declare it: on its own machine first, then, for a package or an MCP server, on every machine holding the same one.
How many things declare it in all; larger than the length of declared_in when that list stopped at its cap.
What this artifact declares, by name, at most 200.
How many things it declares in all; larger than the length of declares when that list stopped at its cap.
Every effective fact about the component this resolved to, ordered by facet then attribute.
Empty is a real state and there are three of them: the artifact offers no key, the catalogue has never heard of it, or it knows the identity and has classified nothing. catalogued.resolution tells them apart.
Which level of the chain spoke: global, curated, curated_over_feed, workspace_override or workspace_added.
All five, because collapsing any pair removes a distinction the operator needs: we decided this and somebody upstream did have different owners and different appeals.
Whether this fact's feed is older than its declared maximum age. Always false for anything resting on no feed — a curation has no clock to fall behind, and neither does a workspace's own decision.
A term, an identifier, or a JSON array for the three list-valued attributes.
Unresolved issues about this artifact, and the worst of them.
0 with a null severity is a real answer: nothing has checked this artifact yet, which is not the same as it being clean.
How this kind of artifact relates to others: declares, declared, instructions, model or other.
The AI supply chain check on this artifact.
Advisories that apply, or may; dismissed ones with their dismissal.
critical|high|medium|low|none, over applying, non-dismissed advisories.
The $slug service categories of the entry.
Raised flags, and dismissed ones with their dismissal.
One entry per feed that answered about this artifact's key.
permissive|copyleft|use_restricted|none|unknown.
The free-text labels somebody applied, alphabetically. Usually empty.
What the registry recognised an artifact as.
This is the outcome of a lookup, distinct from the artifact's category, which says what the artifact is on the machine.
entry, not_catalogued, nothing_to_look_up or checking (task 6.24): what the supply-chain check stored, so the list, the grouping and the inspector read one value. checking is an artifact the check has not reached yet, and is never shown as clean.
Whether any fact under this rests on a feed older than that feed's declared maximum age.
One of the ten component categories. None for unidentified.
The registry's key. None for unidentified.
The bounded, redacted excerpt, or null.
null does not mean the artifact was empty. It means content was never collected — because nothing reads it, or because this kind of artifact can never carry any.
Dependencies a manifest parsed that are out of AI scope, so the band can say "and N other dependencies". null when the agent did not say.
How an MCP server is launched or reached. Everything here was made safe on the machine before it was sent: a key-shaped value is redacted, and a URL is stripped of userinfo, query and fragment.
Names of the environment variables the server is given, as far as its launch arguments show them (-e NAME); never values.
Names of the request headers the server is given (--header Name); never values.
The launcher and the package it runs, e.g. npx @playwright/mcp@1.2.3.
stdio, http or sse.
Which tool this artifact belongs to, or null.
null means unowned, not unknown: a package.json belongs to a project and a weight file to whatever loads it, not to an AI tool.
The declared range (^4.0.0) beside the resolved package_version; null when the version was pinned.
The id of the person this signed-in tool belongs to, resolved from program_account.
null where no tool sign-in points at this artifact — nothing is signed in, the address could not be matched to a person, or it has not been resolved yet since the tool last reported it. It is an id, never a name.
The full email address a tool is signed in as. This is personal data: it identifies a person.
The organisation the tool reports being signed in to. null where the tool states none; few tools report one.
The seat tier the tool reports, exactly as reported and not normalised.
The installed program's posture. All five are null on everything that is not an ai_tool artifact, and independently null on one that is: the six tools differ in what they state about themselves, and a version nobody could read is absent rather than guessed.
The worst open setting issue of an install: what its list row's end says.
The provided check's key: approval_bypass, shell_auto_approved, …
One live session lock, and the decision that locked it.
What matched, in a few words.
The words the person sees on every refused call.
agent (a Hook policy) or server (a Session-log policy).
One tool's settings on one machine, as last read.
RFC 3339, the endpoint's clock.
RFC 3339, this server's clock.
Errors
- 404
No such artifact in this workspace
Run a connector action on a presence
Runs one connector action, such as removing a member, against the record this presence names in the connected service. It applies the same checks and refusals as running the action from the connection: the connection is live, the connector offers the action for this kind of record, and the record is reachable. A vendor's refusal is returned as is, never retried. Needs the permission to manage connections. Only a presence that came from a connector has actions; a tool or machine presence is refused. The attempt appears in the person's history.
Path parameters
Request bodyPresenceActionInput
The descriptor's action id, e.g. remove_member. The record it acts on is the presence's own — a caller does not name one, and cannot name another person's.
Response201
The action that was performed
The descriptor's label — Archive repository — so a row reads as a sentence. The id is beside it because a link is built from the id and a sentence is written with the label.
done | failed | refused.
What started the action: policy (a policy ran it) or operator (a person ran it by hand).
One short word, never a vendor client's Display: one of the five failure words on a failure, not_applicable on a refusal, and accepted / already_done — the vendor's own distinctions — on the two successes that have one. null on a plain success.
Errors
- 400
No such action, or it does not act on this presence's record kind
- 401
No valid session
- 403
Caller lacks connections:manage in this workspace
- 404
No such person or presence in this workspace, or no such record
- 409
This presence has no actions; or the connection is not live, cannot reach that action, or the connector declined
- 502
The vendor could not be reached
- 503
The vendor is rate-limiting this account