Chef Software NodesService API
The NodesService API from Chef Software — 7 operation(s) for nodesservice.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/chef-software-nodesservice-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: external/applications/applications.proto ApplicationsService Nodes Service API
version: version not set
servers:
- url: https://automate.chef.io/api/v0
tags:
- name: NodesService
paths:
/api/v0/nodes:
post:
summary: Create a Node
description: 'Creates a node and adds it to the Chef Automate node manager.
Requires a FQDN or IP address, a user-specified name, and a ssh or winrm credential reference.
Useful for creating nodes for the purpose of running compliance scan jobs.
Example:
```
{
"name": "my-vagrant-node",
"manager":"automate",
"target_config": {
"backend":"ssh",
"host":"localhost",
"secrets":["b75195e5-a173-4502-9f59-d949adfe2c38"],
"port": 22
},
"tags": [
{ "key":"test-node", "value":"is amazing" }
]
}
```
Authorization Action:
```
infra:nodes:create
```'
operationId: NodesService_Create
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Id'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
tags:
- NodesService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Node'
required: true
/api/v0/nodes/bulk-create:
post:
summary: Bulk Create Nodes
description: 'Creates multiple nodes from a list of node data.
`hosts` field is required. Multiple hosts may be defined in this field.
Example:
```
{
"name_prefix": "000-my-ssh-node",
"manager":"automate",
"target_config": {
"backend":"ssh",
"hosts":["localhost","127.0.0.1"],
"secrets":["b75195e5-a173-4502-9f59-d949adfe2c38"],
"port": 22
},
"tags": [
{ "key":"test-node", "value":"is-amazing" },
]
}
```
Authorization Action:
```
infra:nodes:create
```'
operationId: NodesService_BulkCreate
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Ids'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
tags:
- NodesService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Nodes'
required: true
/api/v0/nodes/delete:
post:
summary: Bulk Delete Nodes by Filter
description: 'Deletes a set of nodes that match a filter.
Available filters: account_id, last_contact, manager_id, manager_type, name, platform_name,
platform_release, region, source_id, state, statechange_timerange, status,
last_run_timerange, last_scan_timerange, last_run_status, last_scan_status,
last_run_penultimate_status, last_scan_penultimate_status
Example:
```
{"filters": [{"key": "name", "values": ["vj*"]}]}''
```
Authorization Action:
```
infra:nodes:delete
```'
operationId: NodesService_BulkDelete
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.BulkDeleteResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
tags:
- NodesService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Query'
required: true
/api/v0/nodes/delete/ids:
post:
summary: Bulk Delete Nodes by ID
description: 'Deletes a set of nodes given a list of IDs.
Invalid IDs will be ignored.
Authorization Action:
```
infra:nodes:delete
```'
operationId: NodesService_BulkDeleteById
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.BulkDeleteResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
tags:
- NodesService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Ids'
required: true
/api/v0/nodes/id/{id}:
get:
summary: Show Node Details
description: 'Returns the details for a node given the node ID.
Authorization Action:
```
infra:nodes:get
```'
operationId: NodesService_Read
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Node'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
parameters:
- name: id
description: Unique node ID (UUID)
in: path
required: true
schema:
type: string
tags:
- NodesService
delete:
summary: Delete a Node
description: 'Deletes the node with the node ID.
Authorization Action:
```
infra:nodes:delete
```'
operationId: NodesService_Delete
responses:
'200':
description: A successful response.
content:
application/json:
schema:
properties: {}
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
parameters:
- name: id
description: Unique node ID (UUID)
in: path
required: true
schema:
type: string
tags:
- NodesService
put:
summary: Update Node
description: 'This PUT operation overwrites ALL node details and requires the complete set of node details,
consisting of a FQDN or IP address, a user-specified name, and the ID for an ssh or winrm credential.
Substitute the desired values for the existing node details in the PUT message.
Authorization Action:
```
infra:nodes:update
```'
operationId: NodesService_Update
responses:
'200':
description: A successful response.
content:
application/json:
schema:
properties: {}
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
parameters:
- name: id
description: Unique node ID (UUID).
in: path
required: true
schema:
type: string
tags:
- NodesService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Node'
required: true
/api/v0/nodes/rerun/id/{id}:
get:
summary: List Node Status
description: 'Use this to run an `inspec detect` job on the node, which updates the status to reflect that the node is reachable or unreachable.
Authorization Action:
```
infra:nodes:rerun
```'
operationId: NodesService_Rerun
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.RerunResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
parameters:
- name: id
description: Unique node ID (UUID)
in: path
required: true
schema:
type: string
tags:
- NodesService
/api/v0/nodes/search:
post:
summary: List and Filter Nodes
description: 'Makes a list of nodes.
Supports filtering, pagination, and sorting.
Adding a filter narrows the list of nodes to only those that match the filter or filters.
Supported filters:
account_id, last_contact, manager_id, manager_type, name, platform_name,
platform_release, region, source_id, state, statechange_timerange, status,
last_run_timerange, last_scan_timerange, last_run_status, last_scan_status,
last_run_penultimate_status, last_scan_penultimate_status
Example:
```
{
"filters":[
{"key": "last_scan_status", "values": ["FAILED"]},
{"key": "last_scan_penultimate_status", "values": ["PASSED"]},
{"key": "name", "values": ["MyNode*"]}
],
"page":1, "per_page":100,
"sort":"status", "order":"ASC"
}
```
Authorization Action:
```
infra:nodes:list
```'
operationId: NodesService_List
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Nodes'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/grpc.gateway.runtime.Error'
tags:
- NodesService
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Query'
required: true
components:
schemas:
chef.automate.api.nodes.v1.Query:
type: object
properties:
filters:
type: array
items:
$ref: '#/components/schemas/chef.automate.api.common.query.Filter'
description: Use filters to limit the set of nodes to delete.
order:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Query.OrderType'
sort:
type: string
description: Sort the results on a specific field.
page:
type: integer
format: int32
description: Starting page for the results.
per_page:
type: integer
format: int32
description: The number of results on each page.
chef.automate.api.nodes.v1.Query.OrderType:
type: string
enum:
- ASC
- DESC
default: ASC
description: Return the results in ascending or descending order.
chef.automate.api.nodes.v1.TargetConfig:
type: object
properties:
secrets:
type: array
items:
type: string
description: List of credential IDs for a node.
backend:
type: string
description: Node backend type (ssh, winrm, aws, ssm, azure, gcp).
host:
type: string
description: Node FQDN or IP address.
port:
type: integer
format: int32
title: ssh or winrm connection port
sudo:
type: boolean
description: Uses `sudo` (boolean).
ssl:
type: boolean
description: Check ssl (boolean).
self_signed:
type: boolean
description: Allow self-signed certificate (boolean).
user:
type: string
description: Username from the credential ID for this node.
sudo_options:
type: string
description: Sudo options to use when accessing the node.
hosts:
type: array
items:
type: string
description: List of hostnames (FQDN or IP address) for bulk creating nodes.
description: Details for ssh/winrm access of the node.
chef.automate.api.nodes.v1.RerunResponse:
type: object
chef.automate.api.nodes.v1.BulkDeleteResponse:
type: object
properties:
names:
type: array
items:
type: string
description: List of deleted nodes, by name.
chef.automate.api.nodes.v1.ResultsRow:
type: object
properties:
node_id:
type: string
description: Unique node ID.
report_id:
type: string
description: Unique ID of the report generated by the InSpec scan.
status:
type: string
description: Status of the report (failed, success, skipped).
result:
type: string
description: Error message returned after several failed attempts to contact a node.
job_id:
type: string
description: Unique ID of the scan job that generated the report.
start_time:
type: string
format: date-time
description: Start time on the report.
end_time:
type: string
format: date-time
description: End time on the report.
description: Summary of the last Chef InSpec scan job run on the node.
chef.automate.api.common.query.Filter:
type: object
properties:
key:
type: string
description: Field to filter on.
exclude:
type: boolean
description: "Include matches for this filter.(boolean)\n`true` (default) *includes* all nodes that match this filter. \n`false` *excludes* all nodes that match this filter."
values:
type: array
items:
type: string
description: Field values to filter on.
chef.automate.api.nodes.v1.Ids:
type: object
properties:
ids:
type: array
items:
type: string
description: List of node UUIDs.
google.protobuf.Any:
type: object
properties:
type_url:
type: string
value:
type: string
format: byte
chef.automate.api.nodes.v1.Node:
type: object
properties:
id:
type: string
description: Unique node ID (UUID).
name:
type: string
description: User-specified node name.
platform:
type: string
description: Node platform.
platform_version:
type: string
description: Node platform version.
manager:
type: string
description: Node manager (automate, aws-ec2, aws-api, azure-vm, azure-api, gcp).
tags:
type: array
items:
$ref: '#/components/schemas/chef.automate.api.common.query.Kv'
description: Node tags.
last_contact:
type: string
format: date-time
description: Timestamp of the last `detect` or `exec` job.
status:
type: string
description: Node status (unreachable, reachable, unknown).
last_job:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.ResultsRow'
description: Results of the last compliance scan job for this node.
target_config:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.TargetConfig'
description: Node configuration for ssh or winrm.
manager_ids:
type: array
items:
type: string
description: List of manager IDs for the node.
connection_error:
type: string
description: Last connection error received when trying to contact the node.
state:
type: string
description: Last known node state (running, stopped, terminated).
name_prefix:
type: string
description: Prefix for node name. The full node name is the prefix + the host.
projects:
type: array
items:
type: string
description: List of projects associated with the node.
run_data:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.LastContactData'
description: Most recent node data from the last Chef Infra run results.
scan_data:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.LastContactData'
description: Most recent compliance scan data for the node from the last InSpec scan.
description: Node information.
chef.automate.api.nodes.v1.LastContactData.Status:
type: string
enum:
- UNKNOWN
- PASSED
- FAILED
- SKIPPED
default: UNKNOWN
grpc.gateway.runtime.Error:
type: object
properties:
error:
type: string
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/google.protobuf.Any'
chef.automate.api.nodes.v1.LastContactData:
type: object
properties:
id:
type: string
description: Chef Infra run report ID or InSpec scan report ID.
status:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.LastContactData.Status'
description: Last node report status.
penultimate_status:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.LastContactData.Status'
description: Next-to-last node status report.
end_time:
type: string
format: date-time
description: Last node report endtime.
description: Most recent node data from the latest Chef Infra run and InSpec scan.
chef.automate.api.common.query.Kv:
type: object
properties:
key:
type: string
description: Tag key.
value:
type: string
description: Tag value.
chef.automate.api.nodes.v1.Nodes:
type: object
properties:
nodes:
type: array
items:
$ref: '#/components/schemas/chef.automate.api.nodes.v1.Node'
description: List of nodes.
total:
type: integer
format: int32
description: Total number of nodes in the system.
total_unreachable:
type: integer
format: int32
description: Total number of unreachable nodes in the system.
total_reachable:
type: integer
format: int32
description: Total number of reachable nodes in the system.
total_unknown:
type: integer
format: int32
description: Total number of unknown nodes in the system.
chef.automate.api.nodes.v1.Id:
type: object
properties:
id:
type: string
title: Unique node ID (UUID)