JUjumpcloud
Search

Search Systems

Return Systems in multi-record format allowing for the passing of the filter and searchFilter parameters. This WILL NOT allow you to add a new system.

To support advanced filtering you can use the filter and searchFilter parameters that can only be passed in the body of POST /api/search/* routes. The filter and searchFilter parameters must be passed as Content-Type application/json.

The filter parameter is an object with a single property, either and or or with the value of the property being an array of query expressions.

This allows you to filter records using the logic of matching ALL or ANY records in the array of query expressions. If the and or or are not included the default behavior is to match ALL query expressions.

The searchFilter parameter allows text searching on supported fields by specifying a searchTerm and a list of fields to query on. If any field has a partial text match on the searchTerm the record will be returned.

Sample Request

Exact search for a list of hostnames

curl -X POST https://console.jumpcloud.com/api/search/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "filter": {
    "or": [
      {"hostname" : "my-hostname"},
      {"hostname" : "other-hostname"}
    ]
  },
  "fields" : "os hostname displayName"
}'

Text search for a hostname or display name

curl -X POST https://console.jumpcloud.com/api/search/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter": {
    "searchTerm": "my-host",
    "fields": ["hostname", "displayName"]
  },
  "fields": "os hostname displayName"
}'

Text search for a multiple hostnames.

curl -X POST https://console.jumpcloud.com/api/search/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter": {
    "searchTerm": ["my-host", "my-other-host"],
    "fields": ["hostname"]
  },
  "fields": "os hostname displayName"
}'

Combining filter and searchFilter to search for names that match a given OS

curl -X POST https://console.jumpcloud.com/api/search/systems \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -d '{
  "searchFilter": {
    "searchTerm": "my-host",
    "fields": ["hostname", "displayName"]
  },
  "filter": {
    "or": [
      {"os" : "Ubuntu"},
      {"os" : "Mac OS X"}
    ]
  },
  "fields": "os hostname displayName"
}'
post/api/search/systems

Request

Query parameters

fieldsstring

Use a space seperated string of field parameters to include the data in the response. If omitted, the default list of fields will be returned.

limitinteger

The number of records to return at once. Limited to 100.

skipinteger

The offset into the records to return.

filterstring

A filter to apply to the query. See the supported operators below. For more complex searches, see the related /search/<domain> endpoints, e.g. /search/systems.

Filter structure: The filter syntax follows a consistent pattern of <field>:<operator>:<value> (e.g. department:$eq:Finance)

field = Populate with a valid field from an endpoint response.

operator = Supported operators are:

  • $eq - equals (exact match)
  • $in - equals (multiple match terms). Separate terms by | character: <field>:$in:<term one>|<term two>
    • any item with <field> that matches ANY of the match terms will be returned
    • to use a literal | character inside a match term, it must be "escaped" using a backslash \ ("\|")
      • for GET endpoints, only ONE backslash is needed: costCenter:$in:Atlanta\|Tampa|Chicago
      • for POST endpoints, TWO backslashes are needed due to the nature of JSON: costCenter:$in:Atlanta\\|Tampa|Chicago
      • resulting match terms: "Atlanta|Tampa", "Chicago"
  • $ne - does not equal
  • $nin - does not equal (multiple match terms). Separate terms by | character: <field>:$nin:<term one>|<term two>
    • any item with <field> that DOES NOT match ANY of the match terms will be returned
    • refer to above $in documentation on using literal | character in match terms
  • $lt - is less than
  • $lte - is less than or equal to
  • $gt - is greater than
  • $gte - is greater than or equal to
  • $sw - Finds items where the field value begins with the specified term.

Eventually Consistent Operators = These advanced operators support multiple-term matching and require the x-eventually-consistent API request header to be set as true. Terms within the value must be separated by the | character.

  • $sw - Matches any item where the field value begins with any one of the provided terms. E.g <field>:$sw:<term one>|<term two>
  • $ew - Matches any item where the field value ends with any one of the provided terms. E.g <field>:$ew:<term one>|<term two>
  • $co - Matches any item where the field value contains any one of the provided terms. E.g <field>:$co:<term one>|<term two>
  • $nco - Matches any item where the field value does not contain any of the provided terms. E.g <field>:$nco:<term one>|<term two>

Note: v1 operators differ from v2 operators.

Note: For v1 operators, excluding the $ will result in undefined behavior and is not recommended.

value = Populate with the value you want to search for. Case sensitive.

Examples

  • GET /users?filter=username:$eq:testuser
  • GET /systemusers?filter=department:$in:Finance|IT|Shipping & Receiving - an item with { department: "IT" } will match
  • GET /systemusers?filter=department:$in:Finance \| Sales|IT - an item with { department: "Finance | Sales" } will match
  • GET /systemusers?filter=department:$ne:Accounting
  • GET /systemusers?filter=department:$nin:Finance|IT|Shipping & Receiving - an item with { department: "HR" } will match
  • GET /systemusers?filter=password_expiration_date:$lte:2021-10-24
  • GET /systems?filter[0]=firstname:$eq:foo&filter[1]=lastname:$eq:bar - this will AND the filters together.
  • GET /systems?filter[or][0]=lastname:$eq:foo&filter[or][1]=lastname:$eq:bar - this will OR the filters together.
  • GET /systemusers?filter=department:$sw:Shipping - an item with { department: "Shipping & Receiving" } will match
  • GET /systemusers?filter=department:$sw:Shipping\|Receiving - an item with { department: "Shipping|Receiving Item" } will match
  • GET /systemusers?filter=department:$sw:Shipping|Receiving - an item with { department: "Shipping Item" } will match or an item with { department: "Receiving Item" } will match. Use it with x-eventually-consistent header set to true:

Headers

x-org-idstring
x-eventually-consistentboolean

EXPERIMENTAL! Use to acknowledge eventually consistent data in response.

Request body

fieldsstring
filterobject
searchFilterobject

Response

OK

totalCountinteger

The total number of systems.

Changes

No recorded changes to this operation across all 1 revision of this API.