Skip to main content

HTTP GET Request

squid supports HTTP GET requests and returns JSON.

URL

The URL is https://yourinstance/api/x_a46gh_squidx/v1/data/{configName} where {configName} is the name of the configuration you are requesting. See Predefined Configurations for an overview of all predefined configurations provided by squid.

(The demo server is proxied and rate limited. In order to keep the URL shorter and more human readable, we have removed the x_a46gh_squidx/v1/data/ part of the URL in all links to demo.squid46.io. If you're getting HTTP 429s, slow down.)

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?limit=10

Query Parameter

The configuration on its own is only of limited use. Query parameter allow the caller to request a specific entity, filter results, add relations to the request and further influence the behavior of squid.

Relations

Resolving references and relations is the added value of squid. References are resolved by default. Relations must be explicitly requested.

squid supports three different types of relations:

  • 1:n: These would be e.g., parent-child relations where the child has a reference to the parent.
  • m:n Tables: Basically any table that connects two other tables by referencing records in both tables in one row. While ServiceNow defines Many-to-Many tables (sys_m2m) and these may be used for m:n relations, but squid will happily resolve relations defined in any m:n table.
  • CI Relationships (cmdb_rel_ci): These are the relations you know from ServiceNow based on the M-to-N table cmdb_rel_ci. Technically speaking, CI Relations are the specific m:n table cmdb_rel_ci

See Predefined Relations for an overview of all predefined relations provided by squid.

relations

Relations are requested as query parameter relations. squid accepts this parameter in various formats:

  • relations=rel1,rel2,rel3
  • relations=rel1&relations=rel2&relations=rel3
  • relations=rel1,rel2&relations=rel3

Use whatever fits your calling application best.

Relations may be rendered in various ways. Please see Relations for details.

Inline

Try it: https://demo.squid46.io/cmdb_ci_server_inline_minimal?sys_id=5f9b83bfc0a8010e005a2b3212c9dc07&relations=ci_to_user_group_inline

{
...,
"data": [
{
"asset_tag": "P1000182",
"last_discovered": "2024-07-12T11:21:50Z",
"name": "dbaix901nyc",
"sys_class_name": "cmdb_ci_unix_server",
"sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07",
"sys_mod_count": 12,
"sys_updated_on": "2024-07-17T10:54:43Z",
"user_groups": [
{
"active": true,
"name": "Infrastructure",
"sys_created_by": "admin",
"sys_created_on": "2021-03-30T18:56:30Z",
"sys_id": "6577e5908f972410960c53ac37bdee66",
"sys_mod_count": 0,
"sys_updated_by": "admin",
"sys_updated_on": "2021-03-30T18:56:30Z"
},
{
"active": true,
"description": "CAB approvers",
"name": "CAB Approval",
"sys_created_by": "admin",
"sys_created_on": "2011-09-30T16:30:34Z",
"sys_id": "b85d44954a3623120004689b2d5dd60a",
"sys_mod_count": 0,
"sys_updated_by": "admin",
"sys_updated_on": "2011-09-30T16:30:34Z",
"type": [
"itil"
]
}
]
}
],
...
}

Relation Reference

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?sys_id=5f9b83bfc0a8010e005a2b3212c9dc07&relations=ci_to_user_group

{
...,
"data": [
{
"asset_tag": "P1000182",
"last_discovered": "2024-07-12T11:21:50Z",
"name": "dbaix901nyc",
"sys_class_name": "cmdb_ci_unix_server",
"sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07", <= sys_id of requested server
"sys_mod_count": 12,
"sys_updated_on": "2024-07-17T10:54:43Z"
}
],
"relations": {
"5f9b83bfc0a8010e005a2b3212c9dc07": { <= sys_id of requested server
"user_groups": [
{
"sys_id": "6577e5908f972410960c53ac37bdee66", <= sys_id of user group
"sys_class_name": "sys_user_group"
},
{
"sys_id": "b85d44954a3623120004689b2d5dd60a", <= sys_id of user group
"sys_class_name": "sys_user_group"
}
]
}
},
"referenced": {
"6577e5908f972410960c53ac37bdee66": { <= sys_id of user group
"active": true,
"name": "Infrastructure",
"sys_created_by": "admin",
"sys_created_on": "2021-03-30T18:56:30Z",
"sys_id": "6577e5908f972410960c53ac37bdee66",
"sys_mod_count": 0,
"sys_updated_by": "admin",
"sys_updated_on": "2021-03-30T18:56:30Z"
},
"b85d44954a3623120004689b2d5dd60a": { <= sys_id of user group
"active": true,
"description": "CAB approvers",
"name": "CAB Approval",
"sys_created_by": "admin",
"sys_created_on": "2011-09-30T16:30:34Z",
"sys_id": "b85d44954a3623120004689b2d5dd60a",
"sys_mod_count": 0,
"sys_updated_by": "admin",
"sys_updated_on": "2011-09-30T16:30:34Z",
"type": [
"itil"
]
}
}
}

{configName}.relations

When rendering inline content you might want to request relations for referenced entities. You can do this by adding a query parameter with the following structure:

configName.relations=rel5,rel6

This tells squid to add the given relations whenever an entity is rendered with a configuration configName.

As with relations squid accepts this parameter in various formats:

  • configName.relations=rel5,rel6,rel7
  • configName.relations=rel5&relations=rel6&relations=rel7
  • configName.relations=rel5,rel6&relations=rel7

Use whatever fits your calling application best.

Try it: TODO generate demo entity and create link.

Filters

Most use cases require a specific subset of data. You will seldom want all entities in cmdb_ci_server. squid allows you to define query parameter that restrict what data is returned, e.g. only 'all server with modelIf xxx' or all pc clients updated in the last 14 days.

squid supports the following filters:

encodedQuery

ServiceNow has the concept of 'encodedQueries'.

See ServiceNow: 'Encoded query strings' for details on how to structure a query.
See ServiceNow: 'Operators available for filters and queries' for details on available operators for encodedQueries.

Usage in the context of squid

Using encodedQueries in squid is as simple as defining a query parameter encodedQuery with the encodedQuery as value.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=dbaix901nyc

{
"metadata": {
"powered_by": "arc46.io",
"git": "squid-0.10.8+24-4af2b54",
"build": "2025-09-12T09:39:40.935Z",
"license_max_entities": "Unlimited",
"license_valid_till": "2050-12-31T23:59:59.000Z",
"requested_by": "arc46_rest_demo",
"request_received": "2025-09-14T15:39:25.730Z",
"config": "cmdb_ci_server_minimal",
"row_count": 1,
"provided_filter": "base_name=dbaix901nyc", <= encodedQuery as provided by caller
"combined_filter": "base_name=dbaix901nyc" <= resulting encodedQuery used to retrieve data
},
"data": [
{
"asset_tag": "P1000182",
"last_discovered": "2024-07-12T11:21:50Z",
"name": "dbaix901nyc", <= property that matches encodedQuery
"sys_class_name": "cmdb_ci_unix_server",
"sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07",
"sys_mod_count": 12,
"sys_updated_on": "2024-07-17T10:54:43Z"
}
],
...
}

Correctly defining an encodedQuery

squid uses ServiceNow database views to

a) define what data is retrieved and
b) aggregate data of multiple tables in a single JSON.

Every table that is incorporated into a ServiceNow database view must have a so-called 'Variable prefix'. By convention all squid database views use 'base' as the 'Variable prefix' for the base table. (If you want to use existing database views that do not follow this naming convention, the prefix can be changed in any specific configuration.)

The prefixes for any additional joined tables are documented in the view. Predefined configurations document the used prefixes in the documentation of the configuration e.g., cmdb_ci_server. Look for 'encodedQuery prefix'.

Field Names

squid removes the database view specific 'Variable prefixes' to present the returned JSON in a more expected format. Instead of base_sys_id we return sys_id.

For ServiceNow to understand a given encodedQuery we have to use the field names defined on the database view that we are querying, i.e. we have to set conditions on base_sys_id instead of sys_id.

A future release will take care of this for you, but we're not quite there yet.

Supported encodedQuery Operators

  • ^ / ^OR (AND/OR)
  • =, !=
  • STARTSWITH
  • ISEMPTY / ISNOTEMPTY
  • EMPTYSTRING
  • IN / NOT IN
  • < / <= / >= / > / BETWEEN / MORETHAN / LESSTHAN
  • SAMEAS / NSAMEAS
  • GT_FIELD / GT_OR_EQUALS_FIELD / LT_FIELD / LT_OR_EQAULS_FIELD
  • RELATIVEGT / RELATIVELT
  • VALCHANGES / CHANGESFROM / CHANGESTO
  • DYNAMIC
  • RLQUERY / ENDRLQUERY / SUBQUERY / ENDSUBQUERY / JOIN
  • . (dot walking)

As always with database queries handle with care. The above operators will cause full table scans if the queried fields are not indexed. squid has no plausible way of checking for the existence of an index. (This is technically possible, but the performance impact on each and every request does not justify that approach.)

Restricted encodedQuery Operators

squid is built to deliver large amounts of data in the most performant way possible without impacting your ServiceNow instance. We therefore prevent encodedQueries from executing operations that have the potential of having a noticeable impact on your instance. Anything that would cause a full table scan with text search, order by operations etc. are by default rejected.

As the performance of database queries always depends on the exact query and the presence of indexes our categorizing of operators into critical (restricted) and non-critical (unrestricted) can only be a best effort.

For you to better understand why we are restricting at all we have included the following anecdotal query durations:

Querying cmdb_ci with 1.1 million entries. (These are just anecdotal values to give an impression of what we're talking about. This is NOT a full-fledged performance evaluation. Measurement after 5 warmup queries.)

FieldSTARTSWITHLIKEENDSWITHORDERBY
name - indexed2ms1900ms1900ms48ms
environment - not indexed3500ms3500ms3500ms4700ms

Restricting encoded queries in this way might sound heavy-handed, but in most use cases the caller of squid is coming from a peripheral system that has little to nothing to do with ServiceNow other than that it needs data. The caller will probably neither know nor notice any negative impact he or she is causing.

We however recognize that there may be valid use cases when these operators are necessary and useful. Configurations therefore have a property Restrict Encoded Query that is set to true on all predefined configurations. If this property is set to true the following operators are NOT allowed. If you wish to allow these operators, create a new configuration and set the Restrict Encoded Query to false.

  • % / ENDSWITH
  • * / LIKE / CONTAINS
  • !* / NOT LIKE
  • javascript (Anything that requires javascript is restricted)
  • ORDERBY
  • 123TEXTQUERY321 / 123TEXTINDEXGROUP321

Unless the requested configuration explicitly allows the use of restricted operators, including any of the restricted operators in an encodedQuery is considered an error condition and the request is rejected.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_nameLIKEdbaix901nyc

warning

squid reserves the right to expand the above-mentioned list of restricted encoded query operators at any point in time.

ServiceNow may implement new encoded query operators or undocumented operators may come to our attention. If considered
potentially performance critical, these will be added to the above list at our discretion. Please check the release notes for any changes.

Forbidden for security reasons

  • ^NQ - squid allows configurations to be restricted by the role of the caller and configurations to define view filter that limit the returned data. Both together are a security feature (TODO add link to corresponding documentation).
    ^NQ would add a top level OR clause to any query allowing a caller to circumvent any set restrictions.

Including a forbidden operator in an encodedQuery is considered an error condition and the request is rejected.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=dbaix901nyc^NQbase_name=somethingelse

Use restricted encodedQuery operators in view_filter

Configurations have a property called view_filter. This allows a squid administrator to add an encodedQuery to the configuration. This encodedQuery is NOT restricted in any way as it is defined by a squid administrator.

Time/Date values

Time/Date values are a difficult topic in a ServiceNow context. ServiceNow will accept nonsense Time/Date values without throwing any kind of error and just make a best effort. This will give you the impression of your query being correct until you notice that your results do not match what you were expecting.

The following is based on trial and error:

encodedQuery=base_sys_updated_on>2024-04-22 23:00:00 will be read as '2024-04-22 23:00:00 UTC' as will

encodedQuery=base_sys_updated_on>2024-04-22T23:00:01
encodedQuery=base_sys_updated_on>2024-04-22T23:00:01Z
encodedQuery=base_sys_updated_on>2024-04-22T23:00:01nonsense(!)

warning

encodedQuery=base_sys_updated_on>2024-04-22x23:00:01 will be accepted as valid encodedQuery, but ServiceNow will only interpret the first part, i.e. '2024-04-22' resulting in a query value of '2024-04-22 00:00:00 UTC'.

Please be sure to check any encodedQueries that use Time/Date values.

encodedQuery (HTTP) query parameter format

squid will accept encoded queries as

encodedQuery=yourEncodedQuery

Multiple values are considered an error condition.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=dbaix901nyc&encodedQuery=base_asset_tag=P1000182

sys_id

sys_id allows retrieval of one or more entities by way of their sysId.

squid accepts this parameter in various formats:

  • sys_id=5f9b83bfc0a8010e005a2b3212c9dc07,106c5c13c61122750194a1e96cfde951,1072335fc611227500c0267a21be5dc5

sys_id=5f9b83bfc0a8010e005a2b3212c9dc07&sys_id=106c5c13c61122750194a1e96cfde951&sys_id=1072335fc611227500c0267a21be5dc5

  • sys_id=5f9b83bfc0a8010e005a2b3212c9dc07,106c5c13c61122750194a1e96cfde951&sys_id=1072335fc611227500c0267a21be5dc5

Use whatever fits your calling application best.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?sys_id=5f9b83bfc0a8010e005a2b3212c9dc07,106c5c13c61122750194a1e96cfde951,1072335fc611227500c0267a21be5dc5

updatedBefore / updatedSince / lastDiscoveredBefore / lastDiscoveredSince

updatedBefore, updatedSince and lastDiscoveredBefore, lastDiscoveredSince are utility query parameters intended to make querying both values easier.

The expected DateTime format is ISO8601

  • "YYYY-MM-DD'T'hh:mm(:ss)?'Z'" or
  • "YYYYMMDD'T'hhmm(ss)?'Z'"

The given values are used as to build a filter of

  • base_sys_updated_on<givenDateTimeValue for updatedBefore
  • base_sys_updated_on>=givenDateTimeValue for updatedSince
  • base_sys_last_discovered<givenDateTimeValue for lastDiscoveredBefore
  • base_sys_last_discovered>=givenDateTimeValue for lastDiscoveredSince

Please notice that these values are inclusive for *since and exclusive for *before. (Feel free to give us feedback on this at support.arc46.io)

The 'Variable prefix' (base_) will automatically be adjusted for whatever value is defined in the requested configuration.

squid only accepts and returns ISO8601 Date/Time values (except when encoded in encodedQueries).

Multiple values are considered an error condition.

Try it:

filterOnTags (cmdb_key_value)

Public cloud provider have adopted tags as way of adding metadata to entities (AWS, Azure, GCP) making tags a common and established way of qualifying and accessing configuration items, especially in a dev-ops environment.

ServiceNow supports this concept by way of cmdb_key_value. This table is populated by Cloud Discovery, but may also be populated directly.

Tags are not Tags

ServiceNow uses the term Tags for a slightly different concept. See the link for details on the ServiceNow usage.

squid users are mainly peripheral systems or devOps integrations. These users generally understand 'tag' as described by the major public cloud providers. We try to make life easy for our users.

filterOnTags allows restricting the returned data to only configuration items (cmdb_key_value only allows references to cmdb_ci) that are referenced by at least one key-value entry in cmdb_key_value that matches the given criteria.

Negative filtering, i.e., returning only configurations items that are NOT referenced by a specific key-value entry, is NOT supported.

filterOnTags does NOT change the returned data, i.e., it does not implicitly add tags to the returned configuration items. filterOnTags only filters (nomen-est-omen) data.

See showTags/showTagsInline below for details on how to render tags for configuration items.

filterOnTags query parameter have the following structure:

filterOnTags=tagClause1^ORtagClause2^ANDtagClause3

Following ServiceNow GlideRecord conventions (but contrary to what you might be used to from SQL) ^OR has precedence over ^AND! The above filterOnTags query parameter would result in

(tagClause1 OR tagClause2) AND tagClause3

tagClauses have the following structure:

  • tagName / tagName=* - filters on having a tag with key=tagName ignoring value
  • tagName* / tagName*=* - filters on having a tag with keySTARTSWITHtagName ignoring value
  • tagName= - filters on having a tag with key=tagName andvalue=null
  • tagName*= - filters on having a tag with keySTARTSWITHtagName andvalue=null
  • tagName=value1(,value2,...) - filters on having a tag with key=tagName and a value of value1 OR value2
  • tagName*=value1(,value2,...) - filters on having a tag with keySTARTSWITHtagName and a value of value1 OR value2

Value wildcards (value*) are NOT supported.

Multiple filterOnTags query parameter are AND combined.

filterOnTags=tagName1=value1&filterOnTags=tagName2=value2 is equivalent to filterOnTags=tagName1=value1^ANDtagName2=value2

filterOnTeams (cmdb_rel_team)

filterOnTeams allows restricting the returned data to only configuration items (cmdb_rel_team only allows references to cmdb_ci) that are referenced by at least one entry in cmdb_rel_team that matches the given criteria.

Negative filtering, i.e., returning only configurations items that are NOT referenced by a specific team relation, is NOT supported.

filterOnTeams does NOT change the returned data, i.e., it does not implicitly add team relations to the returned configuration items. filterOnTeams only filters (nomen-est-omen) data.

In order to include Teams relation, request one of the predefined Teams relations.

filterOnTeams query parameter have the following structure:

filterOnTeams=group_type=group1,group2,group3

group_type is e.g. managed_by, approval

group1,group2,group3 are either sysIds of a sys_user_group or the name of a sys_user_group. If a name is given squid will attempt to resolve the name to a sysId. Multiple values are combined as OR condition.

Multiple filterOnTeams query parameter are AND combined.

filterOnTeams=managed_by=group1,group2 will restrict the query to CIs that are
managed_by group1 OR group2.

filterOnTeams=managed_by=group11&filterOnTeams=managed_by=group2 will restrict the query to CIs that are
managed_by group1AND group2.

limit

limit allows you to limit the amount of entities returned. This is of limited use in a production environment, but during development you might want to test your queries with just 10 returned entities instead of 10.000.

As the order of the result set is intentionally undefined, which entities are returned may vary from call to call.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?limit=5

Flags

showBlank

By default, squid will suppress any properties with a null value.

Some client libraries might rely on a stable JSON structure and not play nice with missing JSON properties.

The query parameter showBlank will cause squid to render null JSON properties.

Try it:

showTags

Just as relations, resolving tags requires at least one additional database query. For this reason, tags are only rendered when explicitly requested.

The query parameter showTags tells squid to retrieve and render tags belonging to a configuration item.

squid can render tags in two forms:

As Object

As object. This is a standard JSON object with tagName (key) as property name and value as value.

{
...,
"tags": {
// sys_id of the entity
"995390bccd34f010f8778495fd9bf7f7": {
// key : value
"Owner": "SD DC Ops",
"Location": "San Diego",
"Environment": "Production"
},
"6e5314bccd34f010f8778495fd9bf72b": {
"Owner": "SD DC Ops",
"Environment": "Production",
"Location": "San Diego"
},
"9c5314bccd34f010f8778495fd9bf710": {
"Service": "San Diego Wiki",
"Owner": "SD DC Ops",
"Location": "San Diego",
"Environment": "Production"
},
"821b6357c0a8018b244b9609d7010267": {
"Owner": null
}
},
...
}

While object is easy to read intuitively it is not without problems.

ServiceNow does NOT prevent multiple tags with the same name for a single configuration item. In our example above, nothing prevents a configuration item from having two or more tags with the name Service. As object may only have one property with a given name, it is undefined which of the multiple values is returned.

The structure of the returned object is unknown beforehand, this may lead to problems when deserializing with some JSON frameworks.

For these reasons squid additionally offers

As Array

as array

The exact same data as above (with the addition of the extra 'Service' tag for demonstration purposes) renders as shown below.

{
...,
"tags": {
"995390bccd34f010f8778495fd9bf7f7": [
{
"name": "Owner",
"value": "SD DC Ops"
},
{
"name": "Location",
"value": "San Diego"
},
{
"name": "Environment",
"value": "Production"
}
],
"6e5314bccd34f010f8778495fd9bf72b": [
{
"name": "Owner",
"value": "SD DC Ops"
},
{
"name": "Environment",
"value": "Production"
},
{
"name": "Location",
"value": "San Diego"
}
],
"9c5314bccd34f010f8778495fd9bf710": [
{
// Conflicting name 'Service'
"name": "Service",
"value": "Redundant Tag!"
},
{
// Conflicting name 'Service'
"name": "Service",
"value": "San Diego Wiki"
},
{
"name": "Owner",
"value": "SD DC Ops"
},
{
"name": "Location",
"value": "San Diego"
},
{
"name": "Environment",
"value": "Production"
}
],
"821b6357c0a8018b244b9609d7010267": [
{
"name": "Owner",
"value": null
}
]
},
...
}

This is a much harder read and more verbose, but it is able to render 'conflicting' tagNames and has a predefined structure.

Allowed showTags query parameter are:

  • showTags defaults to showTags=object
  • showTags=object
  • showTags=array

showTagsInline

Tags may also be rendered inline.

preservePrefix

squid uses ServiceNow database views to aggregate data. These views prefix all properties with so-called Variable Prefixes, e.g. base_, lin_, etc.

Most of the time you do NOT want to see these prefixes. There are however use cases where preserving the prefix is essential, e.g. when aggregating tables with name collisions. In the case of two joined tables, one with the prefix base and the other with the prefix other with both having the property name would give us a raw result set with base_name and other_name, with base_name having priority and other_name being ignored. The returned json would only contain one property name with the value of base_name

This will usually be part of the configuration ( See Configurations - Preserve Prefix), but is also available as a query parameter. preservePrefix has precedence over configuration settings.

Try it: https://demo.squid46.io/cmdb_ci_server?limit=1&preservePrefix

{config}.preservePrefix

TODO

showConfig

The config used to render entities is normally not part of the returned json and of no value to the recipient. During development, it may however help to know which configuration was used to render a specific entity.

Referenced entities may be retrieved based on multiple configs depending on the path by which they are referenced. The returned json will be a merge of all data returned by all relevant configs.

The query parameter showConfig will add a property squid_config to each and every returned entity as a string array of all configs used to render the entity.

{
...,
"data": [
{
...,
"squid_config": [
"cmdb_ci_server"
],
...
}
],
"relations": {},
"referenced": {
"067018092b2692103c92f65ac891bf66": {
...
"squid_config": [
"core_company"
],
...
}
}
}

Try it: https://demo.squid46.io/cmdb_ci_server?limit=1&showConfig

lenient

Do not use for production queries

We strongly suggest you use this query parameter ONLY during development.

Use in production can lead to unnoticed missing data!

squid may encounter two different types of errors while processing a request.

  • configuration errors: these are errors when configurations reference non-existent target configs etc. (We might do a deep dive on why we don't validate when a configuration is created, but for now please take our word for it that this is the only realistically workable approach.)
  • query errors: these are errors when the query itself has errors, e.g., requesting a non-existent relation.

squid now has two options:

  • crash hard and early. This is usually the safest option, but developers trying to get their queries right won't have much fun with this approach - or
  • be 'nice' and include warnings in the metadata of the returned JSON pointing developers to what went wrong.

Being nice has the risk of missing data without noticing. Who reads the metadata of a JSON in a technical API? Therefore, squid will, by default, return an error whenever it encounters any type of problem.

Developers tweaking their queries have the option of adding a query parameter lenient. This tells squid to play 'nice' and only add warnings to the metadata.

Some types of errors are not recoverable. Requesting a non-existent configuration will result in a 404 error, regardless of whether lenient is set or not.

We track. Ok?