Pin node osquery version

PUT

/api/v1/nodes/{env}/node/{uuid}/osquery

curl --request PUT \
  --url https://example.com/api/v1/nodes/example/node/example/osquery \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "expires_at": "example", "version": "example" }'

Pins the node to a version of the library, overriding the environment target, optionally until expires_at (RFC 3339, in the future). Changing only the expiry of the pinned version (in the same environment) keeps its request_id, so a version the host rejected is not retried; setting the same version with the same expiry again (or another version) gets a new request_id and retries. Unknown body fields are refused. The installed version and the upgrade result, version, reason and request_id are reported by the host and are untrusted. Environment admins.

Authorizations

• ApiKeyAuth

Parameters

Path Parameters

env

required

string

Environment name or UUID

uuid

required

string

Node UUID

Request Body^required

Pin

Media typeapplication/json

object

expires_at

string

version

string

Example^generated

{
  "expires_at": "example",
  "version": "example"
}

Responses

200

OK

Media typeapplication/json

object

available

Available lists the library version names (no digests), ascending.

Array<string>

installed_version

string

pin

object

expires_at

string

request_id

string

updated_at

string

updated_by

string

version

string

platform_unsupported

PlatformUnsupported is true when the node’s stored platform has no osquery package (for example freebsd), so osctrld cannot upgrade it. Windows is supported.

boolean

rollout

Rollout is set only while the environment’s staged rollout (running or paused) is what the node’s target comes from; null otherwise.

object

eligible_at

string

stage

integer

stages

Array<integer>

state

string

target

object

source

Pin or environment

string

version

string

upgrade

object

reason

string

reported_at

string

request_id

string

result

string

version

string

Example^generated

{
  "available": [
    "example"
  ],
  "installed_version": "example",
  "pin": {
    "expires_at": "example",
    "request_id": "example",
    "updated_at": "example",
    "updated_by": "example",
    "version": "example"
  },
  "platform_unsupported": true,
  "rollout": {
    "eligible_at": "example",
    "stage": 1,
    "stages": [
      1
    ],
    "state": "example"
  },
  "target": {
    "source": "example",
    "version": "example"
  },
  "upgrade": {
    "reason": "example",
    "reported_at": "example",
    "request_id": "example",
    "result": "example",
    "version": "example"
  }
}

400

Bad request, version not in the library or expiry in the past

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

401

Unauthorized

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

403

Forbidden

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

404

Not found

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

413

Request body too large

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

500

Internal server error

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}